> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/tools/api-tools.md).

# API tools

Connecting an assistant or a Toolbox element to an API. Created from the **Tools** tab of an assistant or element, with **Create → Custom tool**.

This is the most technical screen in the platform. You will need the API's documentation open beside you.

## What an API tool does

You describe an API call as a template with placeholders. The assistant decides when the call is needed, works out what to put in the placeholders from the conversation, and uses the response to answer.

For example: an assistant asked *"where is order 10432?"* recognises that it needs the order lookup tool, extracts `10432` as the order number, calls your API, and turns the response into a sentence.

## Identity

| Field                   | What it does                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Display name**        | What people see on the tool card.                                                                             |
| **Display description** | What people see under it.                                                                                     |
| **Visibility**          | **Private** keeps the tool in this organisation. **Direct children** shares it with your child organisations. |
| **Description for LLM** | What the assistant reads to decide whether to use this tool.                                                  |

{% hint style="success" %}
**Description for LLM** is the field that decides whether the tool works. Write several sentences: what the tool does, what information it needs, when to use it, and when not to. *"Looks up the current status and expected delivery date of a customer order. Use it whenever someone asks about an order they have placed. Requires the order number."* beats *"Order lookup"* by a wide margin.
{% endhint %}

## Tool arguments

The arguments are what the assistant fills in. Each one you declare becomes a value it must work out from the conversation.

**Add argument** creates one.

| Field             | What it does                                                                |
| ----------------- | --------------------------------------------------------------------------- |
| **Key**           | The name you reference in the URL, headers or body, for example `order_id`. |
| **Description**   | What this value is. The assistant reads this to know what to extract.       |
| **Type**          | String, Integer, Number, Boolean, Array or Object.                          |
| **Items type**    | For an Array: what it contains. Required.                                   |
| **Properties**    | For an Object: its fields, declared the same way.                           |
| **Default value** | Used when the assistant does not supply one.                                |
| **Required**      | Whether the call cannot proceed without it.                                 |

Argument descriptions matter as much as the tool description. `"query"` tells the assistant nothing; `"The customer's order number, as printed on their confirmation e-mail, e.g. ORD-10432"` tells it exactly what to look for.

Keep arguments few and unambiguous. Every argument is another thing the assistant can get wrong.

## API settings

| Field                    | What to enter                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **API URL**              | The method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) and the endpoint. Reference arguments by their key. |
| **Query parameters**     | JSON. Optional.                                                                                               |
| **Headers**              | JSON. Optional.                                                                                               |
| **Body**                 | JSON. For POST, PUT and PATCH.                                                                                |
| **Number of retries**    | How often to retry a failed call.                                                                             |
| **Timeout (in seconds)** | How long to wait before giving up.                                                                            |

The **Used arguments** readout shows which of your declared arguments the templates actually reference. If an argument is declared but unused, either you have forgotten to place it or you do not need it. Referencing an argument you have not declared blocks saving.

Keep the timeout tight. A user is waiting for an answer while the call runs, and a slow tool makes the whole assistant feel broken.

## Authentication

| Option                             | When to use it                                                              |
| ---------------------------------- | --------------------------------------------------------------------------- |
| **No authentication**              | Public endpoints only.                                                      |
| **API Key**                        | The common case: a fixed token in a header or query parameter.              |
| **User bound JWT**                 | The signed-in user's own token is forwarded, so the API sees who is asking. |
| **OAuth 2.0 (client credentials)** | Machine-to-machine OAuth.                                                   |

### API Key

| Field                       | What to enter                                                              |
| --------------------------- | -------------------------------------------------------------------------- |
| **Headers key**             | The header name, usually `Authorization`.                                  |
| **Key prefix**              | What goes before the value, usually `Bearer` including the trailing space. |
| **Send as query parameter** | Send the credential in the query string instead of a header.               |
| **Secret key**              | The stored secret holding the value.                                       |

### User bound JWT

Set the **Headers key** and **Token prefix**. No stored secret is needed. The signed-in user's token is forwarded.

Use this whenever the target API has its own per-user permissions. It means the assistant can only reach what the person asking is already allowed to see, which is a much better default than one shared credential for everyone.

### OAuth 2.0 (client credentials)

| Field           | What to enter                                |
| --------------- | -------------------------------------------- |
| **Token URL**   | Where to obtain the token.                   |
| **Client ID**   | Your client identifier.                      |
| **Secret key**  | The stored secret holding the client secret. |
| **Headers key** | The header the token is sent in.             |

{% hint style="warning" %}
Credentials always go in a [secret key](/en/for-administrators/tools/secret-keys.md), never typed into a header field. Secrets are stored write-only and are never shown again after saving.
{% endhint %}

## Progress message

An optional line shown in the chat while the tool runs, such as *"Looking up your order…"*, and settable per language. Worth filling in for anything that takes more than a second. Otherwise the user sees nothing happening.

## Testing

Save the tool, switch it on for a test assistant, and try it in **Preview**:

1. Ask something that should trigger it. Does it fire?
2. Ask something that should not. Does it stay out of the way?
3. Ask ambiguously. Does it ask for the missing information rather than guessing?
4. Try a value that will fail: a non-existent order number. Does the assistant handle the error gracefully?

If the tool never fires, the **Description for LLM** is almost always the reason.

## Editing and deleting

The tool card's menu offers **Edit** and **Delete**. You can only edit tools your own organisation created. Tools shared from a parent organisation and platform tools are read-only.