> ## 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. # place an outbound call > dial `toNumber` and connect whoever answers to the agent — the dashboard's **test on phone**. the bot is started and the greeting synthesised while the phone rings, so the callee hears it the moment they pick up. billed, recorded and listed exactly like a web call, with `channel: "phone"`. **caller id.** `fromTrunkId` dials from one of your SIP trunks. `fromNumber` names a number you own: a SIP trunk's, or a rented number that is `active` and already connected to this agent. with neither, the call dials from the agent's connected rented number if it has one, else from the platform's shared number. the agent must be **deployed** and use a voice that can take calls (`muga` or `mulberry`, see `GET /v1/voices`); a draft answers `409 agent_not_deployed`, so a call never runs a configuration you did not release. answers `202` once the carrier accepts the dial; follow the call with `GET /v1/calls/{call_id}`. ## OpenAPI ````yaml /openapi.json post /v1/calls 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/calls: post: tags: - calls summary: place an outbound call description: >- dial `toNumber` and connect whoever answers to the agent — the dashboard's **test on phone**. the bot is started and the greeting synthesised while the phone rings, so the callee hears it the moment they pick up. billed, recorded and listed exactly like a web call, with `channel: "phone"`. **caller id.** `fromTrunkId` dials from one of your SIP trunks. `fromNumber` names a number you own: a SIP trunk's, or a rented number that is `active` and already connected to this agent. with neither, the call dials from the agent's connected rented number if it has one, else from the platform's shared number. the agent must be **deployed** and use a voice that can take calls (`muga` or `mulberry`, see `GET /v1/voices`); a draft answers `409 agent_not_deployed`, so a call never runs a configuration you did not release. answers `202` once the carrier accepts the dial; follow the call with `GET /v1/calls/{call_id}`. operationId: startOutboundCall requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OutboundCallRequest' examples: platform number: value: agentId: ua_fe3277d8 toNumber: '+14155551234' from a rented number: value: agentId: ua_fe3277d8 toNumber: '+14155551234' fromNumber: '+918046800123' from a sip trunk: value: agentId: ua_fe3277d8 toNumber: '+14155551234' fromTrunkId: 019f7c10-2b4e-7d5f-8a6b-7c8d9e0f1a2b with call settings: value: agentId: ua_fe3277d8 toNumber: '+14155551234' callSettings: background_noise: enabled: true volume: 30 idle_ladder: enabled: true nudge_after_seconds: 5 presence_after_seconds: 7 hangup_after_seconds: 5 responses: '202': description: accepted — the call is being placed. content: application/json: schema: $ref: '#/components/schemas/OutboundCallResponse' examples: default: value: callId: 01a05b4d-b1ad-7be0-8d29-04b2fd7e7dca status: calling agentId: 019f6a2e-7c1d-7b3a-9e4f-1a2b3c4d5e6f toNumber: '+14155551234' fromNumber: '+918046800123' '400': description: >- `agent_speaker_not_supported` — the agent's `ttsConfig.voice` is not in the engine's roster (see `GET /v1/voices`). `agent_language_not_supported` — the agent's `language` is not offered by its voice engine. content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_speaker_not_supported: value: error: Speaker is not available for the selected voice code: agent_speaker_not_supported agent_language_not_supported: value: error: Language is not available for the selected voice code: agent_language_not_supported '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 '402': description: >- `insufficient_balance` — the account cannot fund a usable call. top up, or enable auto top-up. content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_balance: value: error: Insufficient prepaid balance for this request code: insufficient_balance '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 '404': description: >- `agent_not_found` — no such agent on this account. `number_not_found` — `fromNumber` is not one of the account's numbers. `sip_trunk_not_found` — no such SIP trunk on this account (or it cannot place calls). content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_not_found: value: error: Agent not found code: agent_not_found number_not_found: value: error: >- No rented number or SIP trunk with that number on this account code: number_not_found sip_trunk_not_found: value: error: Phone number not found code: sip_trunk_not_found '409': description: >- `agent_not_deployed` — only a deployed agent (one with a live version) can answer a number or take a call. `number_not_active` — the rental is still in progress, past due or released. `number_not_connected` — a rented number dials out only for the agent it is connected to. content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_not_deployed: value: error: Deploy the agent before assigning a phone number to it code: agent_not_deployed number_not_active: value: error: That rented number is not active, so it cannot place calls code: number_not_active number_not_connected: value: error: >- That rented number is not connected to this agent. Connect it first with POST /v1/phone-numbers/{id}/agent code: number_not_connected '422': description: >- `agent_phone_model_unsupported` — the agent's voice engine cannot take phone calls (use muga or mulberry). `invalid_request` — a field is missing or malformed. `details` lists every failing field. content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_phone_model_unsupported: value: error: This agent's voice can't be used for phone calls yet code: agent_phone_model_unsupported 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`. `concurrency_limit_exceeded` — every concurrent slot is busy. the body carries `active_requests` and `limit`. `agent_phone_daily_limit` — the account's daily outbound-call cap is reached. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: Rate limit exceeded code: rate_limited limit: 100 current: 101 concurrency_limit_exceeded: value: error: >- Silk is already processing 4 requests for this account. Try again when one finishes, or increase your plan capacity. code: concurrency_limit_exceeded active_requests: 4 limit: 4 agent_phone_daily_limit: value: error: >- You've reached today's limit for phone calls. Try again tomorrow. code: agent_phone_daily_limit headers: Retry-After: description: seconds to wait before retrying (per-key rate limit only). schema: type: integer '502': description: >- `agent_session_failed` — the carrier could not place the call. nothing was charged; safe to retry. content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_session_failed: value: error: Failed to start the voice agent session code: agent_session_failed '503': description: >- `agent_phone_not_configured` — phone calls are unavailable on this deployment. content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_phone_not_configured: value: error: Phone calls are not available right now code: agent_phone_not_configured components: schemas: OutboundCallRequest: properties: agentId: type: string maxLength: 64 minLength: 1 description: >- the agent to run — its UUID or its `ua_…` handle. it must be deployed and use a voice that can take calls. toNumber: type: string description: >- the number to dial, in E.164 (`+` and 7–15 digits; spaces tolerated). fromNumber: anyOf: - type: string - type: 'null' description: >- the caller id, as one of your numbers: a SIP trunk's number, or a rented number that is active and connected to this agent. omit to use the agent's connected rented number, or the platform's number. fromTrunkId: anyOf: - type: string format: uuid - type: 'null' description: dial from this SIP trunk (its id). wins over `fromNumber`. callSettings: anyOf: - $ref: '#/components/schemas/AgentCallSettings' - type: 'null' description: >- call behaviour for this one call. omit to use the agent's stored settings. type: object required: - agentId - toNumber title: OutboundCallRequest description: the body of `POST /v1/calls`. OutboundCallResponse: properties: callId: type: string format: uuid description: >- the call's id. what `GET /v1/calls/{call_id}` and the dashboard's conversations show; store it to correlate the call with your own records. status: type: string description: 'always `calling`: the dial was accepted. follow the call by id.' agentId: type: string format: uuid description: the agent's UUID. toNumber: type: string description: the number dialed, normalised to E.164. fromNumber: anyOf: - type: string - type: 'null' description: >- the caller id the callee sees; null when the platform's shared number was used. type: object required: - callId - status - agentId - toNumber title: OutboundCallResponse description: |- Ack that the call is being placed. ``callId`` is the run id — the row ``GET /v1/calls/{id}`` and the dashboard's conversations show. 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. 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. ````