https://api.echonova.aiDevelopers
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.
What you need
- An API key with Tools on Access. See Give a key tool access.
- The base URL and the
Authorization: Bearer ek_...header from 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.
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 returns each secret's id,
name and creation time, never its value. Send the id as
secretId. - List auth connections returns each
connection's id, name, type and creation time, never its credentials. Send
the id as
connectionIdorauthConnectionId. - 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 orbaseUrlOverride.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.
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:
| 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
- Get a tool
- Create a webhook tool
- Preview an OpenAPI import
- Create an OpenAPI tool
- List secrets
- 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.