welldun. offhook
View on GitHub

Core resources

Agents

An agent is who talks on the call: its instructions, its voice, and the connections it runs on. Create it once and use it for many calls.

Create an agent

POST /v1/agents

Body parameters

FieldTypeDescription
namerequired string The name the agent uses on the call.
instructionsrequired string What the agent is for and how it should behave. Offhook adds its own speaking rules (short turns, no markdown) for you.
companyoptional string The organisation the agent represents.
roleoptional string The agent's role, e.g. scheduling assistant.
first_messageoptional string The first thing the agent says when the call connects.
voice_idoptional string Overrides the voice set on the TTS connection.
llm_modeloptional string Overrides the model, e.g. llama-3.3-70b-versatile.
stt_connection_idrequired uuid Speech-to-text connection.
tts_connection_idrequired uuid Text-to-speech connection.
llm_connection_idrequired uuid Language model connection.
telephony_connection_idoptional uuid Phone carrier connection. Needed to place or answer phone calls.
provider_settingsoptional object Per-provider settings, e.g. { "tts": { "model", "emotion", "speed" }, "llm": { "model" }, "language" }.
tool_idsoptional uuid[] Tools the agent can call during a call. 
curl -X POST http://localhost:8000/v1/agents \
  -H "Authorization: Bearer $OFFHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "company": "Acme Clinic",
    "instructions": "Confirm the appointment. Offer to reschedule if needed.",
    "first_message": "Hi, this is Alex from Acme Clinic.",
    "stt_connection_id": "<stt-connection-id>",
    "tts_connection_id": "<tts-connection-id>",
    "llm_connection_id": "<llm-connection-id>",
    "telephony_connection_id": "<telephony-connection-id>",
    "provider_settings": {
      "tts": { "model": "sonic-3", "emotion": "warm", "speed": 1.0 },
      "language": "en"
    }
  }'

List, retrieve and delete

GET /v1/agents
GET /v1/agents/{id}
DELETE /v1/agents/{id}

Agents can't be edited yet. To change one, create a new agent and delete the old one.