API reference · Agents

Update an agent

PATCHhttps://goblins-call-api.onrender.com/v1/agents/:id

Changes the fields you send and leaves the rest as they are. Calls started afterwards use the new settings; calls already under way keep the ones they started with.

Needs a workspace API key.

Path parameters

idstringRequired

The agent’s ID, such as ua_3f9a1c2b.

Body

namestringOptional1–100 chars

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

systemInstructionstringOptionalup 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.

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.

404

No agent in your workspace has that ID.

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

Notes

  • voice, llm and stt are merged field by field, so you can send just the part you are changing. variables is replaced as a whole: send every variable you want to keep.
curl -X PATCH "https://goblins-call-api.onrender.com/v1/agents/ua_3f9a1c2b" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "voice": {
    "speed": 1.1
  },
  "systemTools": {
    "endCall": true,
    "changeLanguage": true
  }
}'
Response · 200 OK
{
  "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"
  }
}