Skip to main content

Connectors

A connector is how an agent's tools reach an external system — a scheduling backend, a CRM, any HTTP API you want a tool call to hit mid-conversation.

Browsing the catalog​

curl https://convostack.ai/api/connectors/catalog \
  -H "Authorization: Bearer cak_live_..."

Returns the pre-built connector types available (each with the fields it needs). For anything in the catalog, creating a connector is a single call:

curl -X POST https://convostack.ai/api/connectors/from-catalog \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "cal_com",
    "name": "Main scheduling",
    "configValues": { "eventTypeId": "12345" },
    "secretValues": { "apiKey": "cal_live_..." }
  }'

Creating a connector directly​

If you're not using a catalog entry, create one with an explicit mode:

curl -X POST https://convostack.ai/api/connectors \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal booking API",
    "mode": "api_key",
    "provider": "custom",
    "baseUrl": "https://api.example.com",
    "config": { "timeoutMs": 5000 },
    "secret": { "apiKey": "sk_..." }
  }'

mode is one of webhook, oauth, or api_key — it determines which fields on secret are relevant. secret is encrypted at rest and never returned by any read endpoint — not on create, not on get, not on list.

Managing connectors​

# List
curl https://convostack.ai/api/connectors \
  -H "Authorization: Bearer cak_live_..."

# Get one
curl https://convostack.ai/api/connectors/{id} \
  -H "Authorization: Bearer cak_live_..."

# Update non-secret fields
curl -X PATCH https://convostack.ai/api/connectors/{id} \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed connector"}'

# Rotate the secret
curl -X POST https://convostack.ai/api/connectors/{id}/rotate-secret \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"secret": {"apiKey": "sk_new..."}}'

# Revoke — the connector stops working immediately
curl -X POST https://convostack.ai/api/connectors/{id}/revoke \
  -H "Authorization: Bearer cak_live_..."

OAuth-mode connectors​

Connectors with mode: "oauth" are set up through an interactive, browser-mediated consent flow (redirecting to the provider, then back to the dashboard) rather than a plain API call — there's no headless way to complete an OAuth grant. Set these up from Integrations in the dashboard.

Using a connector​

Bind a connector to a tool on an agent or workflow — the tool's config references the connector by id, and the runtime resolves credentials at call time.