API Spec Tools
OpenAPI specifications become callable agent tools with authentication, wildcard references, and per-tool configuration.
On this page
Overview
API Spec Tools import an OpenAPI specification (v3.x) and generate callable tools for agents. Instead of writing custom tool code for every API endpoint, point connic at a spec and it generates the tools.
Import an OpenAPI spec and get callable tools. Each endpoint becomes a tool agents can invoke.
Use patterns like api:my_api.* or api:my_api.users_* in agent YAML to reference groups of tools.
Built-in support for Bearer token, API Key, and Basic auth. Credentials are stored securely and injected at runtime.
Adding an API Spec Tool
Navigate to the API Spec Tools section in the project's composer settings and click Add API Spec. Each API spec tool is configured with the following:
| Field | Description |
|---|---|
| Name | A namespace identifier (lowercase, underscores only). This becomes the prefix used to reference tools in the agent YAML, e.g. api:my_api.*. |
| Source | Upload a JSON or YAML OpenAPI spec file, or provide a URL to fetch the spec from. URL-sourced specs support refresh. |
| Base URL | Override the server URL defined in the spec, for example with a public staging endpoint. Only public HTTP(S) destinations are supported. |
| Authentication | Configure credentials for the target API. Supports Bearer token, API Key, and Basic auth. Credentials are injected into every request the agent makes. |
$ref expansion must be acyclic and is capped at 50 levels, 100,000 traversals, 100,000 resolved nodes, and 8 MiB of resolved output.
Tool Naming
Each endpoint in the spec becomes a tool. When an operationId is defined in the spec, it's used as the base name (converted to snake_case with the action verb moved to the end). Otherwise, the name is derived from the HTTP method and path.
Without operationId (path-based)
Common path prefixes (api, v1, v2, etc.) are stripped.
| Endpoint | Generated Name | Notes |
|---|---|---|
| GET /users | users_get | Method becomes a suffix |
| POST /users | users_create | POST maps to create |
| GET /users/{id} | users_by_id_get | Path params become by_{param} |
| DELETE /users | users_delete | DELETE maps to delete |
| GET /api/v1/users | users_get | /api/v1 prefix is stripped |
With operationId
When an operationId is defined, it takes priority. CamelCase is converted to snake_case and the action verb is moved to the end for consistent wildcard matching.
| operationId | Generated Name | Notes |
|---|---|---|
| getUsers | users_get | CamelCase converted, verb moved to suffix |
| createUser | user_create | Leading verb repositioned |
| user_profile | user_profile_get | No verb detected, method suffix added |
| Method | Verb Suffix |
|---|---|
| GET | _get |
| POST | _create |
| PUT | _update |
| PATCH | _patch |
| DELETE | _delete |
This naming convention enables wildcard grouping. For example, api:my_api.users_* matches all user-related endpoints regardless of HTTP method, and api:my_api.*_get matches all read-only endpoints.
Referencing Tools in Agent YAML
Reference API spec tools in the agent's tools list using the api: prefix followed by the spec name and tool name. Wildcards include groups of tools without listing each one.
tools:
- api:my_api.* # All tools from this spec
- api:my_api.users_* # All user-related tools
- api:my_api.users_get # One specific toolMix API spec tool references with other tool types (predefined tools, database tools, retrieval tools) in the same tools list.
Managing Tools
Configure each imported operation from its tool list.
Toggle individual tools on or off. Disabled tools are excluded from wildcard matches and cannot be invoked by agents, even if explicitly referenced.
Customize each tool's name or description. A refresh retains custom names and descriptions for endpoints matched by HTTP method and path.
Refresh re-fetches the source URL. The fetched endpoints determine the tool set; matching endpoints retain custom names, descriptions, and enabled states.
Authentication Types
Configure authentication when adding or editing an API spec tool. Credentials are stored securely and injected into every request the agent makes to the target API.
| Type | Configuration | Header Sent |
|---|---|---|
| Bearer Token | Token value | Authorization: Bearer {token} |
| API Key | Header name + key value | {header}: {key} |
| Basic Auth | Username + password | Authorization: Basic {base64} |
API spec tool configuration takes effect when agents are redeployed. Navigate to the Deployment page and redeploy the agents that use the spec.