> For the full page index, fetch https://echonova.ai/llms.txt

# Tools API

Create webhook and OpenAPI tools and list the secrets and auth connections they use over the v1 API, with the key permission, credential, URL, retry and rate rules, and a link to every endpoint.

The Tools API lets your server create the tools your agents call. A tool is
either a webhook that calls one URL, or an import of an OpenAPI document
with one operation for each endpoint. You can also list the tools of the
workspace and the secrets and auth connections a tool refers to. They are
the same tools you see under **Tools** in the portal. To give a tool to an
agent, use [Attach tools to an agent](/docs/reference/agents-attach-tools).

## What you need

- An API key with **Tools** on **Access**. See [Give a key tool access](#give-a-key-tool-access).
- The base URL and the `Authorization: Bearer ek_...` header from
  [Authentication](/docs/developers/authentication).
- A member of the workspace who created the key and still has the
  permissions listed below.

## Give a key tool access

A key reaches no tools route until you set **Tools** to **Access** on it:

| Row       | Scope         | What the key may do                                                                                  |
| --------- | ------------- | ---------------------------------------------------------------------------------------------------- |
| **Tools** | `tools:write` | List and read tools, secrets and auth connections, and create and preview webhook and OpenAPI tools. |

This scope stands alone. `agents:write` does not give it, and it does not
give any agent access. The speech rows on the key do not give it
either. A key without the scope gets `403` with
`This API key cannot manage tools.`.

The key acts for the member who created it, and the check runs on every call.
That member needs the permission to manage the developer API, and must be
the workspace owner or have the permission to manage tools. A member who
left the workspace or lost one of these takes the key's access with them.
The error then reads `The member who created this API key cannot manage tools.`.
To set **Tools** to **Access** on a key, you need the permission to manage
tools yourself. Without it the option is off on the key form, and the API
refuses it with `403` and `You cannot give a key scopes you cannot use: tools:write`.
A key that already has **Tools** keeps it when you edit its other rows.
Every text is on [Errors](/docs/developers/errors#tools).

## Secrets by id only

A tool never takes a secret value over the API. Save the value in the vault
in the portal, then refer to it by id:

- [List secrets](/docs/reference/tools-list-secrets) returns each secret's id,
  name and creation time, never its value. Send the id as `secretId`.
- [List auth connections](/docs/reference/tools-list-auth-connections) returns each
  connection's id, name, type and creation time, never its credentials. Send
  the id as `connectionId` or `authConnectionId`.
- A secret goes in a header parameter only.

An id that does not exist, or that belongs to another workspace, is refused with
`Referenced secret not found` or `Referenced credential not found`.

## Credentials are refused inline

The API refuses a plain value that looks like a credential. A refusal names
the field and never repeats its value:

- `Parameter "Authorization" looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.`
  A constant parameter named like a credential, such as Authorization, token,
  api key or cookie.
- `Parameter "X-Trace" has a value that looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.`
  A constant value that starts with Bearer, Basic, Token or Digest, or that has the shape of a JWT.
- `URL query parameter "api_key" looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.`
  A credential-like query key in the webhook URL or `baseUrlOverride`.
- `baseUrlOverride has a query or fragment part that looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.`
  A credential-like key hidden in the query or fragment of the URL.

The field name in each text is the one you sent. Fix it by saving the value
as a secret and sending a secret header with its `secretId`, or by using an
auth connection.

## URL rules

The webhook URL, the `baseUrlOverride` and a document URL must:

- use `https`;
- point at a public host: loopback, private and link-local addresses are refused;
- carry no user name or password.

A failure names the field, such as `webhook.target.url must be a public HTTPS URL (no loopback, private, or link-local addresses)`.

When you read a tool, its URLs hide any user name or password, and show `[redacted]` for the value of a credential-like query parameter.

## Retry a create safely

`POST /v1/tools/webhook` and `POST /v1/tools/openapi` accept an optional
`Idempotency-Key` header, so a retry after a lost response does not make a
second tool. The rules are on
[Retry requests safely](/docs/developers/retries-and-idempotency#idempotency-key).
The preview does not need it: it saves nothing.

## Rate limits and size

The key is limited per endpoint, in addition to the limits on
[Rate limits](/docs/developers/rate-limits):

| Endpoint                         | Calls a minute per key |
| -------------------------------- | ---------------------- |
| `POST /v1/tools/webhook`         | 20                     |
| `POST /v1/tools/openapi`         | 5                      |
| `POST /v1/tools/openapi/preview` | 5                      |

Over the limit the call fails with `429` and a `Retry-After` header with the
seconds to wait.

An OpenAPI body can be up to 6 MB, and an inline document up to 5 MB. A larger
body fails with `413` and `Request body is larger than 6 MB`, before the key is
checked. Send the document as a public `url` instead of inline. An import holds
at most 2000 operations; send `includeOperations` with the ones you need.

## Watch out

A key with `tools:write` can create a tool that sends a stored secret to any
public https URL. Give **Tools** access only to keys you trust with every
secret in the workspace vault, and disable or delete the key when you stop
using it.

## Endpoints

All need **Tools** on **Access**.

- [List tools](/docs/reference/tools-list-tools)
- [Get a tool](/docs/reference/tools-get-tool)
- [Create a webhook tool](/docs/reference/tools-create-webhook-tool)
- [Preview an OpenAPI import](/docs/reference/tools-preview-open-api-tool)
- [Create an OpenAPI tool](/docs/reference/tools-create-open-api-tool)
- [List secrets](/docs/reference/tools-list-secrets)
- [List auth connections](/docs/reference/tools-list-auth-connections)

## FAQ

### Can the API change or delete a tool?

No. The API creates tools and reads them. Change or delete a tool in the portal.

### Can the API save a secret?

No. Secret values and credentials can only be entered in the portal vault.

### Does the key see tools of other workspaces?

No. A key works for the workspace that owns it. A tool id from another
workspace answers `404` with `Tool not found`, the same as an unknown id.

## Related

- [Agents API](/docs/developers/agents-api)
- [Retry requests safely](/docs/developers/retries-and-idempotency)
- [Errors](/docs/developers/errors)
- [Changelog](/docs/developers/changelog)
