API Spec Tools
Import OpenAPI specifications to automatically generate callable tools for your agents. Supports authentication, wildcard references, and per-tool configuration.
Overview
API Spec Tools let you import an OpenAPI specification (v3.x) and instantly get callable tools that your agents can use. Instead of writing custom tool code for every API endpoint, you point Connic at a spec and it generates the tools for you.
Auto-Generated Tools
Import an OpenAPI spec and get callable tools instantly. Each endpoint becomes a tool your agents can invoke.
Wildcard References
Use patterns like api:my_api.* or api:my_api.users_* in agent YAML to reference groups of tools.
Authentication
Built-in support for Bearer token, API Key, and Basic auth. Credentials are securely stored 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 can be refreshed later to pick up API changes. |
| 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. |
Tool Naming
Each endpoint in the spec becomes a tool. When an operationId is defined in the spec, it is 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 automatically.
| 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.
Example agent YAML:
tools: - api:my_api.* # All tools from this spec - api:my_api.users_* # All user-related tools - api:my_api.users_get # One specific tool
You can mix API spec tool references with other tool types (predefined tools, database tools, knowledge tools) in the same tools list.
Managing Tools
After importing a spec, you can configure individual tools without removing or re-importing the entire specification.
Enable / Disable Individual Tools
Toggle individual tools on or off. Disabled tools are excluded from wildcard matches and cannot be invoked by agents, even if explicitly referenced.
Edit Tool Names and Descriptions
Customize the name or description of each tool. Renamed tools keep their custom name across spec refreshes (matched by HTTP method and path). This is useful when auto-generated names are unclear or when descriptions from the spec are missing or too technical.
Refresh URL-Sourced Specs
If the spec was added via URL, click refresh to re-fetch the latest version. New endpoints become new tools, removed endpoints are removed, and existing endpoints preserve any custom names, descriptions, and enabled states.
Authentication Types
Configure authentication when adding or editing an API spec tool. The credentials are securely stored and automatically 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} |
Redeployment Required
Changes to API spec tools -- adding new specs, editing or disabling individual tools, updating authentication, or refreshing URL-sourced specs -- only take effect after redeploying your agents. Navigate to the Deployment page and redeploy to apply your changes.