> ## Documentation Index > Fetch the complete documentation index at: https://docs.rumik.ai/llms.txt > Use this file to discover all available pages before exploring further. # create an agent > create an agent from a prompt, a greeting and a voice. it starts as a draft (`deployed: false`) — deploy it before it can take calls or be connected to a number. typing `{name}` into the prompt or greeting declares an account-wide variable of that name; `{{tool_name}}` attaches a tool. see `GET /v1/voices` for what `ttsConfig` and `language` may be. ## OpenAPI ````yaml /openapi.json post /v1/agents openapi: 3.1.0 info: title: silk api version: 1.0.0 description: >- rumik ai's speech api. synthesize speech with the expressive `muga` model, the faster `mulberry` model or the multilingual `mulberry-1.6` model over http or a streaming websocket session, run conversational voice agents over webrtc, a realtime pcm socket or the phone, and manage everything the agents playground does — agents, voices, variables, tools, phone numbers, sip trunks and outbound calls — with the same api key. contact: name: rumik ai url: https://rumik.ai servers: - url: https://silk-api.rumik.ai description: production security: - bearerAuth: [] tags: - name: speech description: text-to-speech over HTTP and WebSocket. - name: voice agents description: start calls with a deployed agent from your own app. - name: agents description: build, configure, deploy and inspect your agents. - name: calls description: place outbound phone calls and read call history. - name: voices description: the voices, languages and styles an agent may use. - name: variables description: account-wide `{name}` prompt variables and their defaults. - name: tools description: HTTP tools agents call before or during a call. - name: phone numbers description: 'numbers rented through rumik: search, rent, connect, release.' - name: sip trunks description: bring your own numbers over SIP. paths: /v1/agents: post: tags: - agents summary: create an agent description: >- create an agent from a prompt, a greeting and a voice. it starts as a draft (`deployed: false`) — deploy it before it can take calls or be connected to a number. typing `{name}` into the prompt or greeting declares an account-wide variable of that name; `{{tool_name}}` attaches a tool. see `GET /v1/voices` for what `ttsConfig` and `language` may be. operationId: createAgent requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentCreateRequest' examples: default: value: name: support systemInstruction: >- You are the support agent for {company}. Be brief and warm. When the caller asks for a human, {{transfer_call}}. greeting: Hi, this is {company} support. How can I help? ttsConfig: model: mulberry voice: Emma description: >- a female 30s american voice, normal pitch, warm timbre, conversational pacing, calm and reassuring, professional register, like a customer support agent. language: english callSettings: background_noise: enabled: true volume: 30 idle_ladder: enabled: true nudge_after_seconds: 5 presence_after_seconds: 7 hangup_after_seconds: 5 versionName: first cut required: true responses: '201': description: created. content: application/json: schema: $ref: '#/components/schemas/Agent' examples: default: value: id: 019f6a2e-7c1d-7b3a-9e4f-1a2b3c4d5e6f ownerUserId: 019f0000-0000-7000-8000-000000000001 name: support systemInstruction: >- You are the support agent for {company}. Be brief and warm. When the caller asks for a human, {{transfer_call}}. greeting: Hi, this is {company} support. How can I help? ttsConfig: model: mulberry voice: Emma description: >- a female 30s american voice, normal pitch, warm timbre, conversational pacing, calm and reassuring, professional register, like a customer support agent. callSettings: background_noise: enabled: true volume: 30 idle_ladder: enabled: true nudge_after_seconds: 5 presence_after_seconds: 7 hangup_after_seconds: 5 language: english source: scratch templateSlug: null handle: ua_fe3277d8 inboundPhoneNumber: null deployed: false createdAt: '2026-09-11T10:00:00Z' updatedAt: '2026-09-11T10:00:00Z' '401': description: >- `unauthorized` — key missing, malformed, unknown, revoked or expired. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: error: Invalid API key code: unauthorized '403': description: '`forbidden_scope` — the key was created without the `agent` scope.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: forbidden_scope: value: error: This API key lacks the 'agent' scope code: forbidden_scope '409': description: '`limit_exceeded` — the account already has 25 agents.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: limit_exceeded: value: error: You can create up to 25 agents code: limit_exceeded '422': description: >- `invalid_request` — a field is missing or malformed. `details` lists every failing field. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: error: >- body.toNumber: must be an E.164 phone number, e.g. +14155551234 code: invalid_request details: - loc: body.toNumber message: must be an E.164 phone number, e.g. +14155551234 '429': description: >- `rate_limited` — the key's per-minute budget is spent. `Retry-After` says how long to wait; the body carries `limit` and `current`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: Rate limit exceeded code: rate_limited limit: 100 current: 101 headers: Retry-After: description: seconds to wait before retrying (per-key rate limit only). schema: type: integer components: schemas: AgentCreateRequest: properties: callSettings: anyOf: - $ref: '#/components/schemas/AgentCallSettings' - type: 'null' description: >- call behaviour: `background_noise` mixes a quiet room tone under the voice; `idle_ladder` nudges a silent caller and ends the call if they stay silent. both off by default. name: type: string maxLength: 120 description: the agent's name, up to 120 characters. systemInstruction: type: string maxLength: 8000 description: >- the persona — what the agent is, how it behaves. up to 8000 characters. `{name}` reads a variable, `{{tool_name}}` attaches a tool. the language and voice rules are added server-side; do not write them. greeting: type: string maxLength: 1000 description: >- the first thing the agent says. up to 1000 characters; may use `{name}` variables. ttsConfig: $ref: '#/components/schemas/AgentTtsConfig' description: >- the voice: `model` (`muga` | `mulberry` | `spider`), and for mulberry a named `voice` and a style `description`. see `GET /v1/voices`. default `{"model": "muga"}`. language: anyOf: - type: string - type: 'null' description: >- conversation language for the chosen voice — `english`, `hinglish` or `hindi` (see `GET /v1/voices` for what each engine offers). unset = the engine's default. source: type: string default: scratch description: '`scratch` (default) or `template`.' templateSlug: anyOf: - type: string maxLength: 40 - type: 'null' description: >- the template this agent was created from, when `source` is `template`. versionName: anyOf: - type: string maxLength: 120 - type: 'null' description: a name for the v1 this agent is seeded with, e.g. `first cut`. additionalProperties: false type: object required: - name - systemInstruction - greeting title: AgentCreateRequest description: the body of `POST /v1/agents`. Agent: properties: callSettings: $ref: '#/components/schemas/AgentCallSettings' description: the live call behaviour. id: type: string format: uuid description: the agent's UUID. ownerUserId: type: string format: uuid description: your account id. name: type: string systemInstruction: type: string description: >- the persona the **live** version answers with. a pending draft is under `GET /v1/agents/{agent_ref}/versions/draft`. greeting: type: string description: the live greeting. ttsConfig: $ref: '#/components/schemas/AgentTtsConfig' description: the live voice config. language: anyOf: - type: string - type: 'null' description: the live conversation language, or null for the engine's default. source: type: string description: '`scratch` or `template`.' templateSlug: anyOf: - type: string - type: 'null' description: the template it was created from, if any. handle: type: string description: >- the agent's short public handle (`ua_…`). accepted wherever an agent is named. inboundPhoneNumber: anyOf: - type: string - type: 'null' description: >- the E.164 number this agent answers (a rented number or a SIP trunk connected to it), or null. deployed: type: boolean default: false description: >- true once a version has been deployed. until then the agent answers no calls and cannot be connected to a number. createdAt: type: string format: date-time description: when the agent was created. updatedAt: type: string format: date-time description: the last save (draft edits included). type: object required: - id - ownerUserId - name - systemInstruction - greeting - ttsConfig - source - handle - createdAt - updatedAt title: Agent description: >- an agent as the account sees it: identity plus the **live** configuration. Error: type: object properties: error: type: string description: human-readable error message. code: type: string description: machine-readable error code. AgentCallSettings: properties: background_noise: $ref: '#/components/schemas/AgentBackgroundNoise' description: a quiet room tone mixed under the voice on every call. idle_ladder: $ref: '#/components/schemas/AgentIdleLadder' description: >- what happens when the caller goes silent after the agent stops speaking. type: object title: AgentCallSettings description: call behaviour, versioned with the rest of the config. AgentTtsConfig: properties: model: type: string description: >- `muga` (expressive, Hinglish-first), `mulberry` (named voices, styleable) or `spider` (speech-to-speech; no phone calls). voice: type: string description: >- mulberry only: one of the named voices in `GET /v1/voices` (e.g. `Emma`). defaults to the first. description: type: string description: >- mulberry only: a one-sentence voice style — pick one of the presets in `GET /v1/voices`, or write your own. f0_up_key: type: number description: 'mulberry only: pitch shift in semitones (-12..12).' temperature: type: number description: sampling temperature (0.1–1.5). top_p: type: number description: nucleus sampling (0–1). top_k: type: integer description: top-k sampling. repetition_penalty: type: number description: repetition penalty. max_new_tokens: type: integer description: cap on generated tokens per utterance. additionalProperties: false type: object title: AgentTtsConfig description: the voice an agent speaks with. AgentBackgroundNoise: properties: enabled: type: boolean description: mix the room tone in. volume: type: integer description: 0–100. default 30. type: object title: AgentBackgroundNoise description: A quiet room-tone bed mixed under the bot's voice on every call. AgentIdleLadder: properties: enabled: type: boolean description: turn the ladder on. nudge_after_seconds: type: integer description: >- seconds of silence before the agent says one short line to bring the caller back (1–120, default 5). presence_after_seconds: type: integer description: >- seconds after the nudge before it asks whether the caller is still there (1–120, default 7). hangup_after_seconds: type: integer description: >- seconds after that before it says goodbye and ends the call (1–120, default 5). the call's `endReason` is then `customer_ended`. type: object title: AgentIdleLadder description: 'Stale-conversation pinging: nudge → "still there?" → farewell + hang up.' securitySchemes: bearerAuth: type: http scheme: bearer description: >- your rumik api key, e.g. `rk_live_...`. create one in the rumik dashboard. ````