---
name: sarj
description: Integrate Sarj.ai voice calls through REST, Python, or MCP.
---

# Sarj.ai voice calls

Read the [quickstart](https://platform-docs.sarj.ai/getting-started.md) for a first call, the [Python guide](https://platform-docs.sarj.ai/python-sdk.md) for tested client examples, and the [OpenAPI contract](https://platform-docs.sarj.ai/api-reference/openapi.json) for exact fields and errors.

## Select the interface

- REST base: `https://platform-api.sarj.ai/api/v1`; send `Authorization: Bearer $SARJ_API_KEY`.
- Python: `sarj-platform-sdk`, imported as `sarj_platform_sdk`. Check release availability before using scheduling methods; the guide names the required version.
- Call-action MCP: `https://platform-api.sarj.ai/api/v1/mcp`. Use Sarj sign-in with OAuth-capable clients, or a dashboard Bearer key with other clients. Use this server for call operations. Pilot organizations can also read and draft scenario configuration, edit knowledge bases and run automated chat tests; MCP never publishes a prompt. The [MCP guide](https://platform-docs.sarj.ai/mcp-server.md) lists the permission each tool needs. When the tools cannot do what the user asked, call `sendFeedbackToSarj` once per task, in general terms, without secrets or customer data.
- Documentation MCP: `https://platform-docs.sarj.ai/mcp`, public. Use it to search and read documentation; it also exposes a documentation-feedback tool and cannot place calls.

For standalone speech, read [STT](https://platform-docs.sarj.ai/speech-to-text.md) or [TTS](https://platform-docs.sarj.ai/text-to-speech.md). Those services have separate base URLs and credentials; the platform SDK is the voice-call client.

## Place and inspect a call

Obtain an active scenario's UUID from the dashboard and an intended recipient in E.164 format. Do not invent a scenario ID or treat its display name as the identifier. `POST /calls` returns `202 Accepted`; store `data.id` and inspect it with `GET /calls/{call_id}`. A public `GET /health` proves reachability, not credential validity.

Call status and webhook `payload.type` are different contracts. Read the current enum/schema instead of assuming values such as `no_answer` are call statuses.

Reports are asynchronous. Only `completed` and `max_duration_reached` calls are eligible; other terminal states keep `report` null. Even eligible calls can fail report generation. Bound polling by elapsed time and handle a missing report. Use [webhooks](https://platform-docs.sarj.ai/webhooks.md) for push delivery. Prefer `permanent_recording_url`, with `recording_url` as the documented rollout fallback.

## Schedule and retry

Use the [SDK scheduling example](https://platform-docs.sarj.ai/python-sdk.md#schedule-a-call) and the [generated retry-policy reference](https://platform-docs.sarj.ai/api-reference/schedule-configs/create-a-sarjai-schedule-config-retry-policy-for-outbound-calls.md) for fields and bounds. Compute timezone-aware times when sending the request. Cancel or reschedule only while pending; otherwise expect `409 call_not_pending`. Scheduling may be unavailable (`scheduling_disabled`).

Each dial has its own call ID. Correlate attempts with `root_call_id`; `next_retry_at: null` means no next attempt is planned. Scheduled dial retries and HTTP request retries are separate.

## Recover without duplicate calls

Branch on `error.type` (and `error.code` when the type is `conflict`) and retain `meta.request_id`, or the `X-Request-ID` response header when the body ID is null. Set SDK `timeout_ms` for your workload; otherwise it inherits the HTTPX client timeout (5 seconds for SDK-created clients). SDK HTTP retries are disabled by default and are separate from scheduled dial retries. Retry reads with bounded backoff; resolve validation, authorization, call-limit, and `call_not_pending` errors before trying again. An immediate create-call request has no documented idempotency guarantee: after a timeout or connection loss, reconcile the outcome before resubmitting. Do not apply a blanket 5xx retry policy to call creation.

Follow the webhook guide's current acknowledgment deadline, authentication options, and deduplication rules. Never invent HMAC verification support or treat a failed delivery as proof that the call failed.
