API actions (OpenAPI)

An AI assistant can call operations of the customer’s APIs (ERP, CRM, billing, inventory) without writing code or mapping every endpoint by hand: the API is connected once in Integrations with its OpenAPI 3 or Swagger 2.0 specification, and each assistant picks which operations it may use and how.

How it works, in two steps

Centro › Recursos › Integraciones › Añadir integración › API HTTP (Center › Resources › Integrations › Add integration › HTTP API). Name, base URL, how it authenticates (no auth, key in a header, Basic user and password, or Bearer token) and, if you have it, the URL of the swagger.json / openapi.yaml. On save the specification is imported and the Operations panel opens.
Assistant → Actions → API actions. Pick the integration and the operation (only the ones enabled in the hub), write when the model should use it and decide whether it asks for confirmation. Save and try it in the playground.

Keys stay encrypted in the environment and never reach the model: Zoan Cloud makes the call with the integration’s authentication.

Specification and operations

On the API card, Operations opens a panel with four tabs:

Operations: list grouped by tag, with search. Every operation has an Enabled / Disabled switch at environment level: what is not enabled here cannot be used by any assistant. Write operations (POST, PUT, PATCH, DELETE) carry the write chip.
Specification: import or re-import by URL, file or pasted text. Swagger 2.0 is converted to OpenAPI 3 automatically. Re-importing shows the diff (new, changed, removed), keeps what was enabled, and operations that disappear stop being exposed. If the specification published at the URL changes, the card shows “Changed”.
Test: fill in the parameters of an operation and call it from the cloud. Useful to verify the authentication and see the real shape of the response before handing it to an assistant.
Manual: for APIs without a specification, define an operation by hand (method, path with {parameters}, summary and a JSON body example the schema is inferred from). It produces the same structure as an import.

What is stored from the specification is a normalized, trimmed version: per operation, the path, the parameters (path, query and non-security headers), the JSON body and the 2xx response schema. Examples, callbacks, multipart and extensions are dropped. Limits: 500 operations, 40 parameters per operation, 4 nesting levels, 8 MB per file.

The action in the assistant

Each action is a model tool named api_<integration>_<operation> whose inputs are the operation’s parameters plus the top-level properties of the JSON body, with their types, enumerations and descriptions as they come from the specification. Per action you can adjust:

Setting	Purpose
Description	When to use it. Left empty, the operation summary plus `METHOD /path` is used.
Ask for confirmation	Two-turn gate: the assistant summarizes what it is about to do with the resolved values and runs only after the user confirms. On by default for write operations.
Fixed values	Inputs the model does not choose (`centroAtencionOid=1`): injected on every call and removed from the schema.
Hidden parameters	Optional ones that do not apply to the use case.
Response	Path inside the response (`data.items`), fields the model sees and a character cap (6,000 by default). Large responses are trimmed with a note so the model asks for narrower filters.

Suggest instructions in Behavior appends a “How to use the API actions” block to the prompt with the list of actions and the confirm-before-writing rule, so the order of calls lives in business language rather than code.

From each call the model receives estado (HTTP status), datos (projected response) and nota. A 4xx/5xx error arrives with the message from the response body so the assistant can explain it to the user; a 401 or 403 also marks the integration as Reauthorize in the hub until the keys are updated.

Limits and security

30 seconds per call, 1 MB of response, only the integration’s host.
No private-network destinations, unless the integration is marked private network reachable over VPN.
Every call leaves an audit event assistant.api_call (integration, operation, status, duration, conversation). Bodies are not stored.
OAuth2 client credentials and execution through the Agent for APIs reachable only inside the customer’s network come in a later phase.

Catalogs on top of an API integration

HTTP catalogs in Knowledge can pick an API integration instead of a loose credential: the URL may be a relative path (/api/products) and the authentication is taken from the integration.