> ## Documentation Index > Fetch the complete documentation index at: https://docs.sempera.org/llms.txt > Use this file to discover all available pages before exploring further. # Create an outbound call > Places one outbound call on a named line. mode prompt runs only the prompt; the line still supplies the number, consent, do-not-contact, calling hours, caps and billing. The prompt-only mark is not a caller field and skips no check. ## OpenAPI ````yaml https://api.sempera.org/openapi.json post /v1/calls openapi: 3.1.0 info: title: Sempera API version: 1.0.0 description: >- The Sempera API: agents, versions, sessions, calls, phone numbers, tools, integrations, knowledge, tests, evals, workspaces, API keys and webhooks, under one hostname. Read /llms.txt for the guide map. contact: name: Sempera url: https://sempera.org email: hello@sempera.org servers: - url: https://api.sempera.org security: [] tags: - name: Dialing pools description: Owned caller ID pools and side-effect-free selection previews. - name: Messaging description: >- Channel setup and stored conversations; transport activation remains gated. - name: Memory description: Workspace-scoped agent memory configuration and records. - name: Phone description: >- The personal phone plan: previewed, approved calls and texts on one number. - name: Batches description: Consent-bound outbound call batches and their recorded attempts. - name: SMS description: Workspace text conversations, guarded sends and human handoff. - name: Assistant description: >- Owner-session text Assistant settings, mobile linking and the owner's own thread. - name: Experiments description: Observed comparisons between published versions of an agent. - name: Meta description: The API's own front door. - name: Authentication description: Credential classes and scopes. - name: Agents description: 'The core product object: draft, preview, publish, versions.' - name: Sessions description: Channel-neutral conversations, and minting Web voice sessions. - name: Calls description: Phone calls (telephony lifecycle). - name: Phone numbers description: Number-to-agent binding. - name: Tools description: Workspace-level capabilities an agent attaches. - name: Integrations description: Provider connections. - name: Compatibility description: Observed read-only compatibility facades over Sempera canonical stores. - name: Snippets description: >- Versioned workspace code a code tool pins; published versions never change. - name: Knowledge description: Documents an agent answers from. - name: Personas description: Compiled agent identity, one persona per agent. - name: Tests description: Scripted scenarios before deployment. - name: Evals description: Judging completed conversations. - name: Alerts description: An organization's metric alert rules and each rule's trigger log. - name: Workspaces description: The tenant boundary. - name: Credits description: >- A workspace's credit balance and history, read only. Credits pay for building, never for live calls. - name: Automations description: >- Triggers: an event Sempera emits, conditions on it, and one action (a signed webhook or an owner email). - name: Platform description: Deployment identity and capacity, for CI and certification. - name: Organizations description: The membership and billing umbrella. - name: API keys description: Minting and revoking credentials. - name: Webhooks description: Sempera-signed outbound events. - name: Connected clients description: >- Every outside client connected to a workspace, whichever way it signed in, with scopes, last use and revocation. - name: MCP description: >- The MCP endpoint, per-client setup answers, and the revocable connections an owner gives outside AI clients. - name: Models description: Sempera's customer-eligible model catalog. - name: Prompts description: Stored prompts a workspace saves and reuses. - name: Scenarios description: >- An agent's scenarios (situations): create, archive, restore, copy and history. - name: Widgets description: Website widgets, web chat threads and custom components. - name: Citation schemas description: >- The outcome fields frozen with each published version, and how well they are captured. - name: Developer settings description: Developer-facing workspace settings. - name: Contacts description: Workspace contact grouping, resolution and the shared contact schema. - name: Voices description: >- The workspace voice collection: saved cleared voices, desk ratings, team sharing and professional clone preparation. paths: /v1/calls: post: tags: - Calls summary: Create an outbound call description: >- Places one outbound call on a named line. mode prompt runs only the prompt; the line still supplies the number, consent, do-not-contact, calling hours, caps and billing. The prompt-only mark is not a caller field and skips no check. operationId: createCall parameters: - name: Idempotency-Key in: header required: true schema: type: string maxLength: 255 description: >- Replays the stored answer for a retry of the same request; 409 for a different request under the same key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallCreate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Call' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required or invalid credential content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient scope or role content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found (or not in your scope) content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited (Retry-After) content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: - calls:write components: schemas: CallCreate: type: object additionalProperties: false required: - agent_id - consent_basis oneOf: - required: - to - required: - phone_number properties: agent_id: type: string description: >- The line this call goes out on: its number, consent, do-not-contact list, calling hours, caps and billing. With mode prompt it is not the conversation. mode: type: string enum: - agent - prompt default: agent description: >- agent (default): the published agent runs, and task supplements its rules. prompt: the conversation is only the prompt (task or settings.prompt), which is required. The named agent_id remains the line. agent_version, production and environment are refused. prompt_only is not a field; sending it is refused and skips nothing. to: type: string description: Destination phone number, E.164 or national digits. phone_number: type: string description: Alias for to. Send only one name for an option. from: type: string description: Optional owned caller id. from_number: type: string description: Alias for from. dialing_pool_id: type: string format: uuid description: >- Owned number pool for local caller ID. Mutually exclusive with from. Requires workspace entitlement and verified, unexpired A attestation evidence. Exhausted pools refuse without a default-line fallback. name: type: string maxLength: 80 agent_version: type: - string - integer description: >- Installed published agent version id or number. A different version is refused, never substituted. Refused when mode is prompt. agent_version_id: type: - string - integer description: Alias for agent_version. Refused when mode is prompt. production: type: boolean description: >- Resolve the version pinned to the production environment. Refused with AGENT_ENV_UNPINNED when none is pinned. Refused when mode is prompt. use_production: type: boolean description: Alias for production. Refused when mode is prompt. environment: type: string enum: - production description: >- Environment to resolve; production only. Refused when mode is prompt. message: type: string description: Opening message after the required automated-call disclosure. opening: type: string description: Alias for message. first_sentence: type: string description: Alias for message; the automated-call disclosure is always retained. consent_basis: type: string description: Sentence recording why this person opted in. metadata: type: object additionalProperties: type: string description: Existing opening-template context, not a per-call webhook payload. timezone: type: string default: America/Toronto window: type: string default: 09:00-18:00 description: Recipient calling hours, HH:MM-HH:MM. precall_dtmf: type: string description: Keys pressed after connection, before the employee speaks. precall_dtmf_sequence: type: string description: Alias for precall_dtmf. voicemail: type: object description: Alias for settings.voicemail; unsupported actions are refused. webhook: type: string format: uri description: >- URL of an enabled signed endpoint already registered in this workspace. webhook_events: type: array items: const: call.completed minItems: 1 maxItems: 1 voice: type: string description: Alias for settings.voice_id. language: type: string description: Alias for settings.language. task: type: string maxLength: 2000 description: >- Alias for settings.prompt. With mode prompt this is the whole conversation and is required. Otherwise it supplements the agent's published rules. request_data: type: object minProperties: 1 maxProperties: 20 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9_]{0,39}$ additionalProperties: type: string maxLength: 200 description: >- Alias for settings.call_data. Named facts available throughout this call, separate from opening-template metadata. max_duration: type: integer minimum: 2 maximum: 60 description: >- Alias for settings.max_call_minutes; platform safety ceilings still apply. keywords: type: array minItems: 1 items: type: string background_track: type: string enum: - none - 'off' - office - coffee_shop - restaurant block_interruptions: type: boolean description: True blocks interruptions; false allows them. country: type: string description: >- ISO country code for a `to` written without +; one of the countries the App's Send a call page lists. settings: type: object description: >- This call's own settings, checked as the App's Send a call page checks them: voice_id, language, max_call_minutes, interruptibility, acknowledgements, background_noise, voicemail, prompt, keywords, call_data, noise_cancellation and interruption_threshold. Unknown keys are refused. Call: allOf: - $ref: '#/components/schemas/Session' properties: object: const: call mode: type: string enum: - agent - prompt description: >- prompt when the conversation was only the prompt. The line agent is agent_id either way. Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - AGENT_ENV_UNPINNED - CALL_RL_PLAN_ALLOWANCE - CALL_RL_PLAN_CONCURRENCY - CALL_RL_PLAN_DAILY - CALL_RL_PLAN_DAILY_MINUTES - CALL_RL_PLAN_HOURLY - PHONE_AGENT_UNPINNED - PHONE_APPROVAL_EXPIRED - PHONE_APPROVAL_INVALID - PHONE_APPROVAL_REQUIRED - PHONE_COST_UNKNOWN - PHONE_DESTINATION_BLOCKED - PHONE_FUNDING_NOT_LIVE - PHONE_NUMBER_MISSING - PHONE_OUTSIDE_HOURS - PHONE_PLAN_INACTIVE - PHONE_RECIPIENT_OPTED_OUT - SMS_RL_PLAN_ALLOWANCE - SMS_RL_PLAN_DAILY - SMS_RL_PLAN_HOURLY - authentication_required - capability_unavailable - conflict - credits_exhausted - credits_unavailable - csrf_failed - forbidden - gone - idempotency_key_reused - insufficient_scope - internal_error - invalid_credential - method_not_allowed - not_found - owner_setup_required - payload_too_large - provider_failed - provider_timeout - rate_limited - service_unavailable - validation_failed - workspace_suspended message: type: string request_id: type: string field: type: string scope: type: string reason: type: string additionalProperties: true Session: type: object required: - id - object - agent_id - channel properties: id: type: string object: const: session agent_id: type: string channel: type: string enum: - web_voice - web_chat - simulator - phone - test - unknown status: type: string started_at: {} ended_at: {} duration_s: {} outcome: {} language: {} agent_version_id: {} caller: {} summary: {} turns: type: - array - 'null' recording: {} provider: {} call_id: {} runtime_identity: $ref: '#/components/schemas/RuntimeIdentity' additionalProperties: true RuntimeIdentity: type: - object - 'null' description: >- What heard, thought and spoke on this session, as a workspace member reads it: `legs` (stt, llm, tts: each with `engine`, `model`, `machine` as a category, and for tts `ended_on`), `fallbacks` (whether a leg handed over), `worker` (`runtime` origin or hosted, `transport`), `latency` timings, `traffic` (`class`: customer, demo, test or unrecorded) and `verified`, false when the stored block no longer matches its own integrity checksum. Engines and models carry Sempera's sealed names (`engine_...`), never a supplier's. null for a session recorded before the block existed. properties: schema: {} traffic: type: object legs: type: object fallbacks: type: object worker: type: object latency: type: object verified: type: - boolean - 'null' additionalProperties: true securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sempera_sk_... description: >- A workspace API key, sent as Authorization: Bearer sempera_sk_... Each operation names the one scope it needs. Scopes, key kinds and roles are in the Authentication guide. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.