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. Python (SDK)
curl
Python (requests)
TypeScript
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"
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. Python (SDK)
curl
Python (requests)
TypeScript
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 } " )
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 and transcript, or configure webhooks for push updates.
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.
