Custom (OpenAPI)
Connect any HTTP API by uploading its OpenAPI spec — every operation becomes an action your agents and workflows can call.
Beyond the built-in integrations, you can connect any HTTP API by giving Compass its OpenAPI specification. Compass reads the spec and turns each operation into a typed action your agents and workflows can call — no custom code required.
Adding a custom integration
Open the form
Under Studio → Connections, click Custom Integration on the Integrations header.
Provide the spec
Drop in or browse for the API's OpenAPI document, or paste it into OpenAPI Specification. The spec must be JSON. When you upload a file, Name and Description are filled in from the spec; when you paste, fill them in yourself.
Set the base URL (optional)
Enter a Base URL if calls should go somewhere other than the spec's first
server address. Left blank, Compass uses the spec's servers entry.
Create
Click Create Integration. A new card for the API appears under Integrations, just for this project. Open it and choose the Tools tab to see the actions Compass found.
Add a connection
On the new card, click New connection and choose how to authenticate — see below.
How operations become actions
Every GET, POST, PUT, PATCH, and DELETE operation in the spec becomes one
action:
- Name — the operation's
operationId, or the method and path when it has none (for exampleget_pets_petId). - Description — the operation's summary or description. Agents read this to decide when to call the action, so good descriptions in the spec make a real difference.
- Inputs — the path, query, and header parameters, plus the properties of the JSON request body.
- Result — each call returns the response's
status_code,headers, andbody.
GET operations are marked as reads; every other method is a write, so
it starts switched off when you attach the API to an agent. See
Read and write actions.
Connections
A connection to a custom integration authenticates with None or an API
Key. The key is sent in the X-API-Key header unless you change Header
name under Advanced. A connection can also be routed through a
gateway.
Compass doesn't call the API when you save, so a wrong key shows up the first time an action runs.
Changing or removing one
A custom integration can't be edited in the app. To change its spec in place —
keeping its connections — send the new spec through the
API or SDK: PATCH /v1/integrations/{id} with
openapi_spec, or client.integrations.update(id, openapi_spec=…).
To remove one, use Delete on its card's … menu. An integration can't be
deleted while any connection still uses it — which also means
compass integrations register --overwrite, which deletes and recreates it, only
works for an integration nothing is connected to yet.