> ## Documentation Index
> Fetch the complete documentation index at: https://platform-docs.sarj.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> REST quickstart — API key, health check, first call.

## Prerequisites

* A Sarj.ai account
* An API key — see Step 1 below
* Python: `pip install sarj-platform-sdk` (recommended over raw `requests`)

<Note>
  If you're using the [MCP Server](/mcp-server) instead of the REST API, skip Step 1 — MCP clients receive an API key automatically via OAuth on first connect.
</Note>

<Steps>
  <Step title="Get your API key">
    1. Sign in at [platform.sarj.ai](https://platform.sarj.ai/api-keys)
    2. Click **Generate Key**
    3. Copy the key and store it securely

    <Warning>
      Your API key is shown **only once**. Store it as an environment variable:

      ```bash theme={null}
      export SARJ_API_KEY="sk-your-key-here"
      ```
    </Warning>
  </Step>

  <Step title="Verify your setup">
    Confirm the API is reachable with a quick health check.

    <CodeGroup>
      ```python Python (SDK) theme={null}
      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"
      ```

      ```bash curl theme={null}
      curl https://platform-api.sarj.ai/api/v1/health
      ```

      ```python Python (requests) theme={null}
      import requests

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

      ```typescript TypeScript theme={null}
      const response = await fetch("https://platform-api.sarj.ai/api/v1/health");
      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    Expected response:

    ```json theme={null}
    {
      "data": { "status": "ok" },
      "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
    }
    ```
  </Step>

  <Step title="Create your first call">
    Trigger an outbound voice call. Requires your API key and a scenario ID.

    <Tip>
      Create a scenario at [platform.sarj.ai/scenarios](https://platform.sarj.ai/scenarios?status=active); copy its `scn_`-prefixed ID.
    </Tip>

    <CodeGroup>
      ```python Python (SDK) theme={null}
      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}")
      ```

      ```bash curl theme={null}
      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"
        }'
      ```

      ```python Python (requests) theme={null}
      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']}")
      ```

      ```typescript TypeScript theme={null}
      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}`);
      ```
    </CodeGroup>

    Expected response (`202 Accepted`):

    ```json theme={null}
    {
      "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": "..." }
    }
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Response format

All endpoints use a standard response envelope.

**Success:**

```json theme={null}
{
  "data": { },
  "meta": { "request_id": "550e8400-..." }
}
```

**Error:**

```json theme={null}
{
  "error": {
    "type": "unauthorized",
    "message": "Authentication required."
  },
  "meta": { "request_id": "550e8400-..." }
}
```

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

<Warning>
  Include `meta.request_id` in support tickets.
</Warning>