Getting Started

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 instead of the REST API, skip Step 1 — MCP clients receive an API key automatically via OAuth on first connect.

Get your API key

Sign in at platform.sarj.ai
Click Generate Key
Copy the key and store it securely

Your API key is shown only once. Replace ... with it and store it as an environment variable:

export SARJ_API_KEY="..."

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.

from sarj_platform_sdk import SDK

with SDK(timeout_ms=10_000) as sdk:
    print(sdk.system.get_health().data.status)  # "ok"

curl --fail-with-body --max-time 10 https://platform-api.sarj.ai/api/v1/health

import requests

response = requests.get("https://platform-api.sarj.ai/api/v1/health", timeout=10)
response.raise_for_status()
print(response.json())

const response = await fetch("https://platform-api.sarj.ai/api/v1/health", {
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data);

Expected response:

{
  "data": { "status": "ok" },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Create your first call

Trigger an outbound voice call. Requires your API key and a scenario ID.

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.

export SARJ_SCENARIO_ID="550e8400-e29b-41d4-a716-446655440000"
export TEST_PHONE_NUMBER="+966512345678"

import os
from sarj_platform_sdk import SDK

with SDK(api_key_auth=os.environ["SARJ_API_KEY"], timeout_ms=10_000) as sdk:
    res = sdk.calls.create_call(
        phone_number=os.environ["TEST_PHONE_NUMBER"],
        scenario_id=os.environ["SARJ_SCENARIO_ID"],
        language="ar",
    )
    print(f"Call ID: {res.data.id}")

curl --fail-with-body --max-time 10 https://platform-api.sarj.ai/api/v1/calls \
  -H "Authorization: Bearer $SARJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"phone_number\":\"$TEST_PHONE_NUMBER\",\"scenario_id\":\"$SARJ_SCENARIO_ID\",\"language\":\"ar\"}"

import os
import requests

response = requests.post(
    "https://platform-api.sarj.ai/api/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['SARJ_API_KEY']}"},
    json={
        "phone_number": os.environ["TEST_PHONE_NUMBER"],
        "scenario_id": os.environ["SARJ_SCENARIO_ID"],
        "language": "ar",
    },
    timeout=10,
)
response.raise_for_status()
call = response.json()
print(f"Call ID: {call['data']['id']}")

const apiKey = process.env.SARJ_API_KEY;

const response = await fetch("https://platform-api.sarj.ai/api/v1/calls", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: process.env.TEST_PHONE_NUMBER,
    scenario_id: process.env.SARJ_SCENARIO_ID,
    language: "ar",
  }),
  signal: AbortSignal.timeout(10_000),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const call = await response.json();
console.log(`Call ID: ${call.data.id}`);

Expected response (202 Accepted):

{
  "data": {
    "id": "8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b",
    "status": "queued",
    "phone_number": "+966512345678",
    "scenario_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2026-04-12T10:30:00Z"
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Track the call

Store the returned data.id. Fetch it with GET /api/v1/calls/{call_id} for status, recording, transcript, and report, or configure webhooks for push delivery.Reports are generated asynchronously for completed and max_duration_reached calls, typically within a couple of minutes. 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.

Response format

All endpoints use a standard response envelope. Success:

{
  "data": { },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Error:

{
  "error": {
    "type": "unauthorized",
    "message": "Authentication required."
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Always branch on error.type — the message field is for humans only.

Include meta.request_id in support tickets.

Overview

Build

Operate

Getting Started

Prerequisites

Response format

​Prerequisites

​Response format

Prerequisites

Response format