API reference · Agents

Draft an agent with AI

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

Writes an agent from a few sentences about what it should do: a name, instructions, a greeting in the right language, the per-call variables, and the voice, transcription and model for that language. Nothing is saved; send the draft to Create an agent.

Needs a workspace API key.

Body

descriptionstringRequired10–2,000 chars

What the agent is for, who calls it, what it must do and which language it speaks, written as you would tell a new hire.

userIdstringOptional

The workspace the draft is for. A key belongs to one workspace, so this is never needed with one.

Response

draftobject

The fields Create an agent takes, filled in. Change what you like, then POST it to /v1/agents.

summarystring

One line on what was made.

warningsobject[]

What the instructions would get wrong on the chosen voice, each with a code and a message: the check the studio shows under the instructions.

Errors

400

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

400DESCRIPTION_TOO_SHORT

Fewer than 10 characters.

429RATE_LIMITED

More than 30 drafts from this workspace in an hour.

502DRAFT_FAILED

The model did not answer. Try again in a moment.

503DRAFT_UNAVAILABLE

Drafting is not set up on this server.

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

Notes

  • The language is the one the description asks for, else the one it is written in. Say "speaks Tamil" to be sure.
  • The voice engine and voice are chosen for that language from the catalog, and the model is the catalog default; the agent’s rate follows from them when it is created. A draft itself is not billed.
curl -X POST "https://goblins-call-api.onrender.com/v1/agents/draft" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "A receptionist for my dental clinic in Pune. Books appointments, answers questions about timings and fees, and speaks Hinglish."
}'
Response · 200 OK
{
  "draft": {
    "name": "Maya",
    "systemInstruction": "You are Maya, the receptionist for {{clinic_name}}. Book, move and cancel appointments with the doctor…\n\nSpeak in natural everyday Hinglish: Hindi in Devanagari with common English words mixed in.\n\nKeep every reply to one or two short spoken sentences and ask one question at a time. Never read out lists, symbols or formatting.",
    "greetingMode": "static",
    "greetingText": "हेलो, मैं माया बोल रही हूँ {{clinic_name}} से! बताइए, आज मैं आपकी क्या help कर सकती हूँ?",
    "variables": {
      "clinic_name": { "defaultValue": "Sunrise Dental", "description": "The clinic the agent answers for", "contextKey": "$clinic_name" }
    },
    "systemTools": { "endCall": true },
    "voice": { "provider": "sarvam", "model": "bulbul:v4-flash", "language": "hinglish", "speaker": "simran_enhi_customer" },
    "llm": { "provider": "autoloops", "model": "gemma-3-27b-it" },
    "stt": { "provider": "openai", "language": "hi", "detectLanguage": false }
  },
  "summary": "A receptionist for your dental clinic who books appointments and answers questions about timings and fees, in Hinglish.",
  "warnings": []
}