API reference · Calls

Start a call

POSThttps://goblins-call-api.onrender.com/v1/calls

Creates a call, sends the agent into a room and returns what your app needs to join it. The agent greets the caller once they are in.

Works with a workspace API key or the agent’s own key.

Body

agentIdstringRequired

The agent that takes the call. May be left out with an agent’s own key, which already names it.

variablesobjectOptional

Values for the {{variables}} in the agent’s instructions, greeting and tools. Keys and values are strings. A variable left out takes its default.

languagestringOptionaldefault the agent’s language

The language this one call is held in: a language id from the catalog or its iso code, such as ta. Letter case and a region are ignored, so ta-IN is Tamil too. A language other than Hindi or English needs an agent whose voice.provider is cartesia and whose stt.provider is openai. Left out, or the same as the agent’s language, the call runs exactly as the agent is saved. See the Calls guide.

participant.identitystringOptional1–128 chars; default user

Your identifier for the caller. Returned as participantIdentity and written into the join token.

participant.namestringOptionalup to 128 chars

A display name for the caller.

participant.ttlSecondsintegerOptional60–86,400; default 3,600

How long the join token can be used to enter the room.

metadataobjectOptional

Any JSON of your own, such as an order or session ID. Kept on the call and sent back in every webhook for it.

webhooksobject[]Optionalup to 5

Destinations for this call’s events only. Each has url, events and an optional secret of at least 16 characters.

roomNamestringOptionalletters, digits, _ and -; up to 128

A room name of your own. Your workspace ID is put in front of it. One is generated when left out.

configobjectOptional

Overrides for this one call, on top of the agent’s settings. Only the prompt, vad, turn and call sections may be set: see the Calls guide.

Response

callIdstring

The call’s ID, for every later request about it.

livekitUrlstring

The address your app connects to.

tokenstring

A join token for this room and this participant only. This, not your API key, is what you hand to a browser or phone.

languagestring

The call’s language as an ISO code, such as ta. Returned only when the request sent language; the call keeps it as metadata.language.

Errors

400AGENT_REQUIRED

No agentId was sent with a workspace key.

400

The body failed validation. details lists each field and what is wrong with it.

400UNSUPPORTED_LANGUAGE

language cannot be used for this call. The response carries a reason: unknown when it is not a language the platform lists, and then languages holds the codes it does; voice when the agent’s voice or transcription cannot follow it.

402INSUFFICIENT_BALANCE

The workspace balance is zero or below. The response carries balance and currency.

403CONFIG_FIELD_NOT_ALLOWED

config tried to set something outside prompt, vad, turn and call. fields lists what was refused.

404AGENT_NOT_FOUND

No agent in your workspace has that ID.

429RATE_LIMITED

Too many calls started in a minute. Wait retryAfterSeconds and try again.

429WORKSPACE_CONCURRENCY_LIMIT_REACHED

Your workspace is already on as many calls as its plan allows at once.

429CONCURRENCY_LIMIT_REACHED

The platform is at capacity. Retry shortly.

Every request can also answer 401, 429 and 500: see Errors.

Notes

  • A call nobody joins is not billed.
  • When the balance would run out mid-call, the call is ended at that point instead of going into debt.
  • A call ends after 24 hours at the latest, with the reason max-duration.
curl -X POST "https://goblins-call-api.onrender.com/v1/calls" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "ua_3f9a1c2b",
  "participant": {
    "identity": "customer_123"
  },
  "variables": {
    "customer_name": "Divya"
  },
  "metadata": {
    "orderId": "A-1042"
  }
}'
Response · 201 Created
{
  "callId": "8f1c2c1e-7b1a-4e0a-9c55-2f6f0d3b1a90",
  "roomName": "call_8f1c2c1e7b1a",
  "livekitUrl": "wss://…",
  "token": "eyJhbGciOiJIUzI1NiJ9…",
  "participantIdentity": "customer_123"
}