# Draft an agent with AI

`POST` `https://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](https://www.cracklehq.com/docs/authentication).

## Body

- `description` (string, required, 10–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.
- `userId` (string, optional): The workspace the draft is for. A key belongs to one workspace, so this is never needed with one.

## Response

- `draft` (object): The fields Create an agent takes, filled in. Change what you like, then POST it to `/v1/agents`.
- `summary` (string): One line on what was made.
- `warnings` (object[]): 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.
- `400` `DESCRIPTION_TOO_SHORT`: Fewer than 10 characters.
- `429` `RATE_LIMITED`: More than 30 drafts from this workspace in an hour.
- `502` `DRAFT_FAILED`: The model did not answer. Try again in a moment.
- `503` `DRAFT_UNAVAILABLE`: Drafting is not set up on this server.

Every request can also answer `401`, `429` and `500`: see [Errors](https://www.cracklehq.com/docs/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.

Request:

cURL:

```bash
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."
}'
```

Node.js:

```js
const response = await fetch('https://goblins-call-api.onrender.com/v1/agents/draft', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRACKLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'A receptionist for my dental clinic in Pune. Books appointments, answers questions about timings and fees, and speaks Hinglish.',
  }),
});
if (!response.ok) throw new Error(await response.text());
const data = await response.json();
```

Python:

```python
import os
import requests

response = requests.post(
    "https://goblins-call-api.onrender.com/v1/agents/draft",
    headers={"Authorization": f"Bearer {os.environ['CRACKLE_API_KEY']}"},
    json={
        "description": "A receptionist for my dental clinic in Pune. Books appointments, answers questions about timings and fees, and speaks Hinglish.",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
```

Response · 200 OK:

```json
{
  "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": []
}
```

Source: https://www.cracklehq.com/docs/reference/agents/draft