> ## 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 a campaign > dial every contact of an audience with a **deployed** agent (UUID or handle), from one of your own numbers (`phoneLineKind` `rented` or `sip_trunk` with `phoneLineId`), up to `maxConcurrentCalls` at a time. `retryEnabled` redials contacts who don't pick up after `retryDelayMinutes` (15, 20, 30 or 60), up to `maxRetries` (1–6). `scheduledAt` (up to 90 days ahead) starts it later; left out, it starts now. `contextColumns` picks the audience columns appended to the agent's prompt on every call (left out, the audience's own choice; `[]`, none). every call is billed and recorded like any phone call. ## OpenAPI ````yaml /openapi.json post /v1/campaigns 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 or the faster `mulberry` 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. - name: campaign audiences description: >- the contact lists (CSV uploads) a campaign calls, and the columns its agent gets. - name: campaigns description: >- outbound campaigns: an agent calling an audience from your own number, with retries and a start time — and every call's transcript and recording. paths: /v1/campaigns: post: tags: - campaigns summary: create a campaign description: >- dial every contact of an audience with a **deployed** agent (UUID or handle), from one of your own numbers (`phoneLineKind` `rented` or `sip_trunk` with `phoneLineId`), up to `maxConcurrentCalls` at a time. `retryEnabled` redials contacts who don't pick up after `retryDelayMinutes` (15, 20, 30 or 60), up to `maxRetries` (1–6). `scheduledAt` (up to 90 days ahead) starts it later; left out, it starts now. `contextColumns` picks the audience columns appended to the agent's prompt on every call (left out, the audience's own choice; `[]`, none). every call is billed and recorded like any phone call. operationId: createCampaign requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CampaignCreateRequest' examples: default: value: name: Diwali offer audienceId: 01a0b054-6f82-7193-ce0f-1a2b3c4d5e6f agentId: ua_fe3277d8 phoneLineKind: sip_trunk phoneLineId: 019f7c10-2b4e-7d5f-8a6b-7c8d9e0f1a2b contextColumns: - column: city description: where they live maxConcurrentCalls: 2 retryEnabled: true retryDelayMinutes: 15 maxRetries: 2 scheduledAt: null responses: '201': description: created. content: application/json: schema: $ref: '#/components/schemas/Campaign' examples: default: value: id: 01a0c165-7093-72a4-df10-2b3c4d5e6f70 name: Diwali offer description: null status: running audienceId: 01a0b054-6f82-7193-ce0f-1a2b3c4d5e6f audienceName: September leads contextColumns: - column: city description: where they live userAgentId: 019f6a2e-7c1d-7b3a-9e4f-1a2b3c4d5e6f agentName: acme support phoneLineKind: sip_trunk phoneLineId: 019f7c10-2b4e-7d5f-8a6b-7c8d9e0f1a2b fromNumber: '+918035763212' maxConcurrentCalls: 2 retryEnabled: true retryDelayMinutes: 15 maxRetries: 2 scheduledAt: null startedAt: '2026-10-01T09:05:00Z' completedAt: null cancelledAt: null lastError: null notice: null noticeAt: null stats: total: 120 pending: 95 dialing: 1 inProgress: 1 retryWaiting: 3 completed: 18 failed: 2 skipped: 0 createdAt: '2026-10-01T09:05:00Z' updatedAt: '2026-10-01T09:20: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 '404': description: >- `agent_not_found` — no such agent on this account. `campaign_audience_not_found` — no such audience on this account. `campaign_phone_line_not_found` — the line is not one of your rented numbers or outbound SIP trunks. `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 campaign_audience_not_found: value: error: Contact group not found code: campaign_audience_not_found campaign_phone_line_not_found: value: error: Phone line not found code: campaign_phone_line_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. 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 '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 '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: CampaignCreateRequest: properties: name: type: string maxLength: 120 description: the campaign's name, up to 120 characters. description: anyOf: - type: string maxLength: 1000 - type: 'null' audienceId: type: string format: uuid description: the audience to call. phoneLineKind: $ref: '#/components/schemas/CampaignPhoneLineKind' description: >- `rented` (a number rented through rumik) or `sip_trunk` (one of your SIP trunks). see `GET /v1/campaigns/phone-lines`. phoneLineId: anyOf: - type: string format: uuid - type: 'null' description: the rented number's or SIP trunk's id. contextColumns: anyOf: - items: $ref: '#/components/schemas/ContextColumn' type: array - type: 'null' description: >- the audience columns appended to the agent's prompt on every call, each with a description. left out, the audience's own choice; `[]`, none. maxConcurrentCalls: type: integer maximum: 50 minimum: 1 default: 1 description: >- calls kept live at once, up to your account's limit (`maxConcurrentCalls` of `GET /v1/campaigns/phone-lines`). default 1. retryEnabled: type: boolean default: false description: redial a contact who didn't pick up. retryDelayMinutes: type: integer minimum: 1 default: 15 description: 'minutes before a redial: 15, 20, 30 or 60.' maxRetries: type: integer maximum: 6 minimum: 0 default: 1 description: redials per contact, 1–6. scheduledAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 time to start, up to 90 days ahead. left out or null, it starts now. agentId: type: string maxLength: 64 minLength: 1 description: >- the agent making the calls: its UUID or `ua_…` handle. must be deployed. type: object required: - name - audienceId - phoneLineKind - agentId title: CampaignCreateRequest description: the body of `POST /v1/campaigns`. Campaign: properties: id: type: string format: uuid name: type: string description: anyOf: - type: string - type: 'null' status: type: string audienceId: anyOf: - type: string format: uuid - type: 'null' audienceName: type: string contextColumns: anyOf: - items: $ref: '#/components/schemas/ContextColumn' type: array - type: 'null' userAgentId: anyOf: - type: string format: uuid - type: 'null' agentName: anyOf: - type: string - type: 'null' phoneLineKind: type: string phoneLineId: anyOf: - type: string format: uuid - type: 'null' fromNumber: anyOf: - type: string - type: 'null' maxConcurrentCalls: type: integer retryEnabled: type: boolean retryDelayMinutes: type: integer maxRetries: type: integer scheduledAt: anyOf: - type: string format: date-time - type: 'null' startedAt: anyOf: - type: string format: date-time - type: 'null' completedAt: anyOf: - type: string format: date-time - type: 'null' cancelledAt: anyOf: - type: string format: date-time - type: 'null' lastError: anyOf: - type: string - type: 'null' notice: anyOf: - type: string - type: 'null' noticeAt: anyOf: - type: string format: date-time - type: 'null' stats: $ref: '#/components/schemas/CampaignStats' createdAt: type: string format: date-time updatedAt: type: string format: date-time type: object required: - id - name - description - status - audienceId - audienceName - userAgentId - agentName - phoneLineKind - phoneLineId - fromNumber - maxConcurrentCalls - retryEnabled - retryDelayMinutes - maxRetries - scheduledAt - startedAt - completedAt - cancelledAt - lastError - notice - noticeAt - stats - createdAt - updatedAt title: Campaign description: an outbound campaign, with live counts of its contacts by state. Error: type: object properties: error: type: string description: human-readable error message. code: type: string description: machine-readable error code. CampaignPhoneLineKind: type: string enum: - rented - sip_trunk - platform title: CampaignPhoneLineKind description: |- Which caller id a campaign dials from: a rented number, one of the user's own SIP-trunked numbers, or the platform's default number. ContextColumn: properties: column: type: string maxLength: 64 minLength: 1 description: a header of the audience's CSV (case-insensitive). description: type: string maxLength: 200 default: '' description: >- what the column means, written for the agent (up to 200 characters). shown to it as `- city (where they live): Pune`. type: object required: - column title: ContextColumn description: an audience column given to the agent, and what it means. CampaignStats: properties: total: type: integer default: 0 pending: type: integer default: 0 dialing: type: integer default: 0 inProgress: type: integer default: 0 retryWaiting: type: integer default: 0 completed: type: integer default: 0 failed: type: integer default: 0 skipped: type: integer default: 0 type: object title: CampaignStats description: How many of the campaign's contacts sit in each state. securitySchemes: bearerAuth: type: http scheme: bearer description: >- your rumik api key, e.g. `rk_live_...`. create one in the rumik dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.