Core resources

Connections

A connection stores one provider credential, encrypted, for your agents to use. You pay your providers directly; Offhook adds nothing on top.

Supported providers

Each connection has a provider_kind and a provider_name from this list:

Kind	Providers	Secret fields
`stt`	`deepgram`	`api_key`
`tts`	`cartesia`, `openai`	`api_key`; Cartesia also takes `voice_id`
`llm`	`groq`, `gemini`, `openrouter`, `openai`	`api_key`
`telephony`	`plivo`, `twilio`	Plivo: `auth_id`, `auth_token`, `from_number` Twilio: `account_sid`, `auth_token`, `from_number`

Create a connection

POST /v1/connections

Body parameters

Field	Type	Description
`name`required	string	A label for the connection. Must be unique within your tenant.
`provider_kind`required	string	One of `stt`, `tts`, `llm` or `telephony`.
`provider_name`required	string	A provider from the table above.
`secrets`required	object	The provider's secret fields from the table above. Never returned.

curl -X POST http://localhost:8000/v1/connections \
  -H "Authorization: Bearer $OFFHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-plivo",
    "provider_kind": "telephony",
    "provider_name": "plivo",
    "secrets": {
      "auth_id": "MA…",
      "auth_token": "…",
      "from_number": "+14155550100"
    }
  }'

{
  "id": "6a1d3f8e-2c4b-4a9e-b7d1-0e5f3c8a2b61",
  "name": "my-plivo",
  "provider_kind": "telephony",
  "provider_name": "plivo",
  "created_at": "2026-10-15T10:00:00Z"
}

Creating a connection with a name you already use returns 409.

List and retrieve

GET /v1/connections

GET /v1/connections/{id}

Both return the fields shown above. Secrets are never included in any response.

Rotate a secret

PATCH /v1/connections/{id}

Send a new secrets object, a new name, or both. The new secret is encrypted in place, and agents using the connection pick it up on their next call.

Delete a connection

DELETE /v1/connections/{id}

Returns 409 while an agent still uses the connection. Delete that agent first.