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. Store it as an environment variable:

export SARJ_API_KEY="sk-your-key-here"

Verify your setup

Confirm the API is reachable with a quick health check.

import os
from sarj_platform_sdk import SDK

sdk = SDK(api_key_auth=os.environ.get("SARJ_API_KEY", ""))
print(sdk.system.get_health().data.status)  # "ok"

curl https://platform-api.sarj.ai/api/v1/health

import requests

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

const response = await fetch("https://platform-api.sarj.ai/api/v1/health");
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 a scenario at platform.sarj.ai/scenarios; copy its scn_-prefixed ID.

import os
from sarj_platform_sdk import SDK

sdk = SDK(api_key_auth=os.environ["SARJ_API_KEY"])
res = sdk.calls.create_call(
    phone_number="+966512345678",
    scenario_id="scn_abc123",
    language="ar",
)
print(f"Call ID: {res.data.id}")

curl -X POST https://platform-api.sarj.ai/api/v1/calls \
  -H "Authorization: Bearer $SARJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+966512345678",
    "scenario_id": "scn_abc123",
    "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": "+966512345678",
        "scenario_id": "scn_abc123",
        "language": "ar",
    },
)
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: "+966512345678",
    scenario_id: "scn_abc123",
    language: "ar",
  }),
});

const call = await response.json();
console.log(`Call ID: ${call.data.id}`);

Expected response (202 Accepted):

{
  "data": {
    "id": "call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b",
    "status": "queued",
    "phone_number": "+966512345678",
    "scenario_id": "scn_abc123",
    "created_at": "2026-04-12T10:30:00Z"
  },
  "meta": { "request_id": "..." }
}

Track the call

Calls progress queued → in_progress → completed. Poll GET /api/v1/calls/{call_id} for recording_url, transcript, and report, or configure webhooks for push updates. The outcome report is generated asynchronously and typically appears within a couple of minutes after a call completes; calls that end without completing (e.g. failed or unanswered) never get one. In rare failure cases even a completed call never receives a report, so cap how long you poll and treat the webhook as authoritative.

Response format

All endpoints use a standard response envelope. Success:

{
  "data": { },
  "meta": { "request_id": "550e8400-..." }
}

Error:

{
  "error": {
    "type": "unauthorized",
    "message": "Authentication required."
  },
  "meta": { "request_id": "550e8400-..." }
}

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

Include meta.request_id in support tickets.

​Prerequisites

​Response format

Prerequisites

Response format