OpenAPI tool operations

Importing a document gives you one record per operation. Look here for what each record holds, how an operation authenticates, how to stop the agent calling one, and what your API receives when it does. To import a document in the first place, see OpenAPI tools.

The operation list

Open the tool from an agent's Tools tab or from the Tool Library page, then open its Endpoints tab. It has a rail of operations on the left and the selected operation's contract on the right.

The rail is a flat list headed "Endpoints (N)", with a tally such as "12 Enabled, 3 Disabled" beside it and a search box placeholdered "Search endpoints". Each row shows the method, the path and the description, with its switch. An empty search result reads "No endpoints match your filter." An operation the document marks as changing state shows a mutating badge in its contract pane.

Clicking a row opens its contract. Parameters is a table with the columns Name, In, Type, Required and Description, and the request body appears under a heading carrying its content type, for example Body (application/json). An operation with neither reads "No parameters" and "No documented fields".

What each operation carries

Contracts are read one level deep: a local $ref is followed once, application/json wins when an operation declares several body media types, and a part that cannot be read is skipped rather than failing the import. An operation whose parameters could not be read still imports and still works; its contract simply shows nothing. A tool imported before contracts were kept reads "Endpoint details aren't stored for this tool."

Auth modes

An imported tool has one auth connection for the whole API, chosen at import. Each operation may override it, and inherit is the default.

The contract pane labels the outcome on the operation's header line: auth: <name> for the tool's connection, auth override: <name> for a per-operation one and no auth when neither applies.

Whatever the mode, a connection arrives at your API as an Authorization header. Four kinds exist: basic, bearer, OAuth2 client credentials and OAuth2 JWT. That header is written last, so it replaces any header of the same name a fixed value set, comparing names without regard to case.

The import dialog does not offer a per-operation mode. Each operation uses the tool's connection unless it was set up otherwise at import.

Fixed field values

A field the document declares can be pinned to a value the agent never sees. There are two kinds:

A pinned field is taken out of the operation before the agent ever sees it, so the agent is not told it exists, and it is put back when the call is made. If the agent supplies an argument whose name matches a pinned field, that argument is thrown away before the request is built. A secret's value is read when the call is made, placed into a header, never logged and never echoed back.

Neither is set in the import dialog. Both are set at import and checked against the operation's real contract, and three refusals are possible:

In the contract pane an operation with pinned fields gains a Value column, and a secret-backed row is marked with a Secret chip instead of a value.

Call it well

Anything the agent can fill, the agent can fill wrongly. Pin the values that never change, and leave the agent only the fields a caller actually supplies.

Recommended

apiKey     header  pinned to a workspace secret
tenantId   query   pinned constant "acme"
orderId    path    filled by the agent from what the caller said

Less effective

apiKey     header  filled by the agent
tenantId   query   filled by the agent
orderId    path    filled by the agent

Enabling and disabling an operation

Each rail row carries a switch. Turning it off stops the agent calling that operation, and the change is written immediately rather than on a save button.

A switched-off operation can still surface in a search, so it may appear in the retrieval bench. The call itself is refused before anything reaches your API, and the agent gets operation_disabled back instead of a result. The change takes effect at once, including in a conversation already running. An operation you have never switched counts as enabled.

What your API receives

Every call goes to the base URL you set on the tool. Pinned path constants are substituted first, then {curly} placeholders are filled from what the agent supplied and URL encoded; a placeholder with no value is left as it is. Remaining values are placed by method: GET, HEAD and DELETE put them in the query string, and every other method puts them in a JSON body with Content-Type: application/json. Pinned constants and secrets go on next, and the Authorization header is written last.

Your API sees an ordinary request. There is no EchoNova signature on it, and nothing on it identifies the conversation it came from. Take an operation GET /orders/{orderId}, a caller asking about order 4512, a pinned query constant locale and a bearer auth connection:

GET /orders/4512?locale=en HTTP/1.1
Host: api.example.com
Authorization: Bearer <resolved from the auth connection>

You can reproduce that request against your own API while you are checking an import:

curl "https://api.example.com/orders/4512?locale=en" \
  -H "Authorization: Bearer $MY_API_TOKEN"

import os
import requests

response = requests.get(
    "https://api.example.com/orders/4512",
    params={"locale": "en"},
    headers={"Authorization": f"Bearer {os.environ['MY_API_TOKEN']}"},
    timeout=15,
)
print(response.status_code, response.text[:500])

const response = await fetch('https://api.example.com/orders/4512?locale=en', {
  headers: { Authorization: `Bearer ${process.env.MY_API_TOKEN}` },
});
console.log(response.status, (await response.text()).slice(0, 500));

Your reply comes back to the agent as a status, an ok flag and a body, and the agent reads it and keeps talking.

When a call fails

A failed call comes back to the agent as a tool result rather than as an HTTP failure, so the agent can read it and respond. Each one carries a status and an error string.

A non-success status from your own API is not in that table. It is passed through as it stands, with your response body, so a 404 from your service reaches the agent as a 404.

One retry exists. When your API answers 401 and the call used an OAuth2 connection, EchoNova fetches a fresh token and sends the request once more.

Limits

FAQ

How do I stop the agent calling one operation?

Switch it off in the rail. The change applies at once, and the agent is told the operation is unavailable instead of your API being called.

Can I give one operation a different credential from the rest of the API?

Not from the import dialog. Each operation uses the tool's connection unless it was set up otherwise at import, and the contract pane shows which applies as auth: <name>, auth override: <name> or no auth.

Can the agent see a pinned API key?

No. A pinned field is removed from the operation before the agent sees it and put back when the call is made, and a secret's value is never returned by any screen or response.

Why did my API get a request with an unfilled {placeholder}?

The agent supplied no value for that path parameter. Mark the parameter required in the document, or pin it to a constant if it never varies.

Does my API get told which conversation a call belongs to?

No. The request carries only the credential and the values you configured.

Related

• OpenAPI tools: import the document and follow its states
• The retrieval bench: check which operation a caller's wording reaches
• Auth connections: the credentials these modes point at
• Workspace secrets: the values you pin to a header
• Tools overview: how the four kinds differ