Quickstart

Make your first API call in 5 minutes.

1. Create an API Key

1. Go to dialogbrain.com
2. Open Settings → Developer
3. Click Create New Key, give it a name
4. Copy the key immediately — it's only shown once

Store it safely; we'll use it as $API_KEY below.

2. Create an Agent

With curl:

curl -X POST https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Booking assistant",
    "prompt_text": "You confirm bookings for Acme Support."
  }'

Response:

{
  "id": 42,
  "name": "Booking assistant",
  "slug": "booking-assistant",
  "status": "active",
  "text_engine": "agentic",
  "execution_config": {
    "model": "deepseek-v4-flash-nothink",
    "max_tokens": 8192,
    "temperature": 0.7,
    "max_iterations": 10
  },
  "tool_config": {
    "allow_web_search": true,
    "allow_calendar": true
  },
  "created_at": "2026-08-22T03:26:59.034064+00:00"
}

With Python SDK:

import asyncio
from dialogbrain import DialogBrainClient

async def main():
    async with DialogBrainClient(api_key="$API_KEY") as client:
        agent = await client.agents.create(
            name="Booking assistant",
            prompt_text="You confirm bookings for Acme Support.",
            idempotency_key="my-unique-key-1"
        )
        print(f"Created agent {agent['id']}")

asyncio.run(main())

Or synchronously:

from dialogbrain import SyncDialogBrainClient

with SyncDialogBrainClient(api_key="$API_KEY") as client:
    agent = client.agents.create(
        name="Booking assistant",
        prompt_text="You confirm bookings for Acme Support.",
        idempotency_key="my-unique-key-1"
    )
    print(f"Created agent {agent['id']}")

3. Place a Voice Call

Place an outbound call to a contact and let the agent handle it.

With curl:

curl -X POST https://api.dialogbrain.com/api/v1/calls \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 42,
    "target": "+1 555 0100"
  }'

Response (202 Accepted — call is now dialing):

{
  "call_id": "5c8d7f2a9e1b3c4d5e6f7a8b9c0d1e2f",
  "status": "dialing",
  "channel": "phone",
  "target": "+1 555 0100",
  "thread_id": 15028
}

The response is received immediately (status 202). The actual call is being placed in the background. You can check its status with GET /calls/{call_id}.

With Python SDK:

call = await client.calls.create(
    agent_id=42,
    target="+1 555 0100",
    idempotency_key="my-unique-call-1"
)
print(f"Call {call['call_id']} status: {call['status']}")

4. Get the Transcript

Once the call ends, retrieve the transcript:

curl https://api.dialogbrain.com/api/v1/calls/5c8d7f2a9e1b3c4d5e6f7a8b9c0d1e2f/transcript \
  -H "X-API-Key: $API_KEY"

Response:

{
  "call_id": "5c8d7f2a9e1b3c4d5e6f7a8b9c0d1e2f",
  "metadata": {},
  "turns": [
    {
      "turn_number": 1,
      "role": "agent",
      "text": "Hello, this is Acme Support. How can I help?",
      "ts": "2026-08-22T03:26:59.034064+00:00"
    },
    {
      "turn_number": 2,
      "role": "user",
      "text": "I'd like to book an appointment tomorrow at 2pm.",
      "ts": "2026-08-22T03:27:02.034064+00:00"
    },
    {
      "turn_number": 3,
      "role": "agent",
      "text": "I've confirmed your appointment for tomorrow at 2pm. You'll receive a confirmation email shortly.",
      "ts": "2026-08-22T03:27:05.034064+00:00"
    }
  ]
}

With Python SDK:

transcript = await client.calls.get_transcript("5c8d7f2a9e1b3c4d5e6f7a8b9c0d1e2f")
for turn in transcript["turns"]:
    print(f"{turn['role']}: {turn['text']}")

5. Next Steps

• Webhooks — listen for call.ended, message.new, and other events
• REST API Reference — explore all endpoints (agents, calls, conversations, contacts, messages, webhooks, billing)
• Authentication — learn about workspace scoping and key rotation
• Python SDK — full SDK documentation