API Spec Tools
Import OpenAPI specifications to generate callable tools for your agents. Supports authentication, wildcard references, and per-tool configuration.
On this page
Overview
API Spec Tools let you import an OpenAPI specification (v3.x) and get callable tools your agents can use. 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 your 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 your 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 your 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. Useful when pointing at a staging or internal endpoint instead of the spec's default server. |
| 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 your agent's tools list using the api: prefix followed by the spec name and tool name. Wildcards let you 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 toolYou can mix 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.