Quickstart

Check your key

API keys start with gat_ and travel in an Authorization: Bearer header — the only form /v2 accepts. GET /v2/user/me is the cheapest way to confirm a key works, and it tells you the two numbers you will care about later: how many calls you may run at once, and how much credit is left.

curl "$GRAINE_API/user/me" \
  -H "Authorization: Bearer $GRAINE_KEY"

POST /v2/api-keys mints further keys, but it requires the keys:write scope, which is denied by default — no key already in circulation can mint another one until an account admin grants it. Your first key therefore comes from your account admin, not from this API.

Create an agent

An agent is a name, the instructions it follows, the line it opens with, and how it hears, speaks and thinks. display_name is the only required field — everything else can be added later with a PATCH. The body uses the same shape GET /v2/agents/{agent_id} returns, so what you send is what you will read back.

Anything in {braces} in the prompt or the greeting becomes a variable you fill per call in step 4.

curl -X POST "$GRAINE_API/agents" \
  -H "Authorization: Bearer $GRAINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Appointment Reminder",
    "summary": "Confirms tomorrow'"'"'s appointment and offers to reschedule.",
    "category": "conversation",
    "labels": ["reminders"],
    "greeting_message": "Hi, am I speaking with {callee_name}?",
    "prompts": {
      "conversation": {
        "system": "You are a scheduling assistant for {company_name}. Confirm that the customer still wants their appointment tomorrow. If they cannot make it, offer to reschedule. Keep every reply to one or two short sentences, and end the call once the appointment is confirmed or moved."
      }
    },
    "configuration": {
      "runtime": {
        "speech_recognition": {
          "provider": "deepgram",
          "model": "nova-2",
          "language": "en"
        },
        "voice_synthesis": {
          "provider": "cartesia",
          "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091",
          "model": "sonic-3",
          "speed": 1.0
        },
        "language_model": {
          "provider": "azure",
          "model": "azure/gpt-4o-mini",
          "config": { "max_tokens": 150, "temperature": 0.2 }
        }
      }
    }
  }'

Three things in that response are worth pointing at now, because they surprise people later:

• version is 2, not 1. A new agent starts at version 2, and every successful update increments it. Your body is applied exactly as a PATCH would apply it, so a field means the same thing on create as on update.
• variables is read from the text. It lists the placeholders the prompt and the greeting actually contain, as plain names, every time the agent is read. To add a variable, write it into the text.
• What you did not send is filled in. The policy objects under configuration and the flat conversation_config come back with defaults; change any of them later with a PATCH that sends only that control.

Creating an agent takes longer than most requests, and configuring extraction can need a language-model call, so allow this request up to two minutes before your client gives up — not the usual 15 seconds.

Deploy it

Placing a call does not check the agent's status: a DRAFT agent can already be dialled in step 4. What ACTIVE does is mark the agent live and lock its configuration, so nothing edits a running agent by accident. Move it to ACTIVE with a PATCH — only the fields you send are changed, and every successful update increments version.

curl -X PATCH "$GRAINE_API/agents/6c6f4cc3-f56c-479d-8422-7f76694daa29" \
  -H "Authorization: Bearer $GRAINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'

Place the call

POST /v2/calls dials immediately. to_number is E.164; omit from_number to let Graine pick a caller ID registered to your organization.

variables fills the {tokens} in the prompt and the greeting. metadata is merged over variables, so a key present in both takes the metadata value. An app talking to the same agent sends the same names through its SDK — Send your user's details to the agent.

curl -X POST "$GRAINE_API/calls" \
  -H "Authorization: Bearer $GRAINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
    "to_number": "+14155550123",
    "variables": {
      "callee_name": "Priya",
      "company_name": "Northgate Dental"
    },
    "metadata": {
      "crm_record": "cust_88213"
    },
    "record": true,
    "timeout_seconds": 30
  }'

Five outcomes are worth handling explicitly:

Read the execution

The same execution_id answers from "scheduled" through "ringing" and "in-progress" to a terminal status. Read status and is_terminal; you never have to branch on which phase the call is in.

curl "$GRAINE_API/calls/8f2a1c7e-5d34-4b19-9c60-1a7f0b2e4d88" \
  -H "Authorization: Bearer $GRAINE_KEY"

Polling

Poll the execution until is_terminal is true. The terminal statuses are:

Everything else — queued, scheduled, rescheduled, initiated, ringing, in-progress — is in flight and is_terminal is false. A call the person answers but the agent never joins ends failed, with an error.message that begins agent_unavailable.