API reference · Agents

Create an agent

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

Creates an agent in your workspace. Only a name and instructions are required; the voice, language and model start from the platform’s defaults.

Needs a workspace API key.

Body

namestringRequired1–100 chars

What the agent is called in the studio and in call logs.

systemInstructionstringRequiredup to 25,000 chars

The agent’s instructions: who it is, what it does and how it should speak. May contain {{variables}} and mention tools as @tool_name.

greetingModeenumOptionalgenerate · static · none; default generate

generate has the model write the opening line from greetingInstruction, static speaks greetingText as written, and none waits for the caller to speak first.

greetingTextstringOptional

The opening line when greetingMode is static. May contain {{variables}}.

greetingInstructionstringOptional

What the opening line should do when greetingMode is generate. May contain {{variables}}.

voiceobjectOptional

How the agent sounds. Anything left out is filled in with the platform’s default.

voice.providerstringOptional

The voice engine, one of the ttsProviders in the catalog.

voice.languagestringOptional

The language the agent speaks, one of the languages in the catalog, such as hi, hinglish or en.

voice.speakerstringOptional

The voice: an ID from the voice library, or a named speaker of the engine. The catalog’s voices list an engine’s named speakers; one that carries languages speaks those languages, so choose it together with voice.language.

voice.speednumberOptional0.2–2, default 1

Speaking rate.

voice.volumenumberOptional0.5–2

Loudness, with 1 as the voice’s own level. Engines without a volume control ignore it.

voice.emotionstringOptional

A delivery the engine supports, such as calm. Engines without emotions ignore it.

llmobjectOptional

The model that writes the replies. provider and model come from the llmModels in the catalog; temperature (0–2) and maxTokens are snapped to what that model allows.

sttobjectOptional

How the agent listens. provider is one of the sttProviders in the catalog; send it alone to change engines. An engine that lists languages transcribes only those, and an agent set to any other language is transcribed by the default engine. language is the ISO code of the language callers speak, such as hi or ta; English words in it are understood as well. Set it alongside voice.language when the agent speaks anything but the default language.

variablesobjectOptional

The variables the instructions use, by name. Each is { "defaultValue": "…", "description": "…" }; the default applies when a call does not send that variable.

toolIdsstring[]Optional

The agent’s tools that are switched on. Naming another agent’s tool gives this agent a copy of it under a new ID.

toolsobject[]Optional

Tool definitions to save with the agent, each shaped like the body of Create a tool. A definition whose name matches one of the agent’s tools updates that tool.

documentIdsstring[]Optional

The workspace’s documents the agent answers from. IDs that are not documents of the workspace are dropped.

systemToolsobjectOptional

Built-in actions the agent may take on its own: { "endCall": true, "changeLanguage": true }.

webhookUrlstringOptional

A URL that receives every event of this agent’s calls. Must be a public address. An empty string removes it.

embedobjectOptional

What the agent’s publishable key may do from a web page: enabled, allowedOrigins (up to 20 hosts; empty allows any site), maxCallSeconds (30–3,600, default 300) and dailySpendLimit (default 5). Off until enabled is true.

Response

agent.idstring

The ID you pass as agentId when starting a call.

agent.apiKeystring

The agent’s own key, which can only run calls for this agent.

Errors

400

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

400URL_NOT_ALLOWED

The URL is not a public http(s) address.

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

Notes

  • id, userId, apiKey, costPerMinute and stats are set by the platform. Sending them has no effect.
curl -X POST "https://goblins-call-api.onrender.com/v1/agents" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "systemInstruction": "You answer calls for Sunrise Dental. Help callers book, move or cancel an appointment. Keep every reply to one or two short sentences.",
  "greetingInstruction": "Greet {{customer_name}} warmly in one short sentence.",
  "voice": {
    "language": "en"
  },
  "variables": {
    "customer_name": {
      "defaultValue": "there"
    }
  },
  "systemTools": {
    "endCall": true
  }
}'
Response · 201 Created
{
  "agent": {
    "id": "ua_3f9a1c2b",
    "userId": "usr_8c1d2e3f4a5b",
    "name": "Front desk",
    "costPerMinute": 0.07,
    "apiKey": "gs_agent_…",
    "webhookUrl": "",
    "systemInstruction": "You answer calls for Sunrise Dental…",
    "greetingMode": "generate",
    "greetingText": "",
    "greetingInstruction": "Greet {{customer_name}} warmly in one short sentence.",
    "voice": { "provider": "cartesia", "language": "en", "speaker": "…", "speed": 1 },
    "llm": { "provider": "…", "model": "…", "temperature": 0.6, "maxTokens": 90 },
    "stt": { "provider": "…", "language": "en", "detectLanguage": false },
    "variables": { "customer_name": { "defaultValue": "there" } },
    "toolIds": [],
    "tools": [],
    "systemTools": { "endCall": true },
    "stats": { "totalCalls": 0, "totalSeconds": 0, "totalCost": 0 },
    "createdAt": "2026-10-11T08:12:44.000Z",
    "updatedAt": "2026-10-11T08:12:44.000Z"
  }
}