Skip to main content

Prerequisites

  • A Sarj.ai account
  • An API key — see Step 1 below
  • Python: pip install sarj-platform-sdk (recommended over raw requests)
If you’re using the MCP Server with an OAuth-capable client instead of the REST API, skip Step 1. The client receives an API key through Sarj sign-in on first connect. Other MCP clients need a dashboard API key.
1

Get your API key

  1. Sign in at platform.sarj.ai
  2. Click Create API key and choose an expiration
  3. Select calls:write to place calls and calls:read to retrieve results
  4. Copy the key and store it securely
Your API key is shown only once. Replace ... with it and store it as an environment variable:
2

Verify your setup

Confirm the API is reachable with a health check. This endpoint is public, so a successful response does not validate your API key.
Expected result: data.status is "ok".
3

Create your first call

Trigger an outbound voice call. Requires your API key and a scenario ID.Run the TypeScript example on Node.js 22 or newer, in a server or trusted local script. Keep your API key out of browser code.
Create an active scenario at platform.sarj.ai/scenarios and copy its UUID. Set SARJ_SCENARIO_ID to that value and TEST_PHONE_NUMBER to a number you intend to call, in E.164 format. The UUID below is illustrative; replace it with your own scenario.
A successful request returns 202 Accepted. Save data.id; see the response schema.
4

Track the call

Fetch the returned ID with GET /calls/, or use webhooks for push delivery.Reports are generated asynchronously for completed and max_duration_reached calls. Other terminal states never receive a report; rare generation failures can leave an eligible call without one too. Bound your polling and handle a missing report. Prefer permanent_recording_url; during its rollout, fall back to recording_url when the permanent field is null.See the Python SDK guide for an inspection example and future-call scheduling.
For response envelopes, authentication, and request IDs, see the API overview. Use the SDK recovery guide to decide when to retry.
Last modified on November 10, 2026