Skip to main content

Sarj.ai Platform SDK

Typed synchronous and asynchronous Python client for the Sarj.ai Developer API. Requires Python 3.10 or newer.

Install

pip install sarj-platform-sdk

Or add it to a project with uv add sarj-platform-sdk. Create an API key at platform.sarj.ai/api-keys and store it in SARJ_API_KEY. Never commit credentials.

Create and inspect a call

Set SARJ_SCENARIO_ID to the scenario UUID copied from your dashboard and TEST_PHONE_NUMBER to a deliberate test destination in E.164 format. This operation places a real outbound call.

import os

from sarj_platform_sdk import SDK

with SDK(
    api_key_auth=os.environ["SARJ_API_KEY"],
    timeout_ms=10_000,
) as sdk:
    created = sdk.calls.create_call(
        phone_number=os.environ["TEST_PHONE_NUMBER"],
        scenario_id=os.environ["SARJ_SCENARIO_ID"],
        language="ar",
    )
    call = sdk.calls.get_call(call_id=created.data.id)
    print(call.data.id, call.data.status, call.meta.request_id)

Creation returns 202 Accepted; it does not mean the call has completed. Reports arrive asynchronously and can remain absent. Use a bounded polling deadline or webhooks to consume results. See the quickstart for the full lifecycle.

To schedule a call, pass a timezone-aware datetime as scheduled_at. Omitting this argument or passing None creates an immediate call. Validate untyped input first: malformed objects such as {} can be treated as omitted.

Async calls and client lifetime

Every generated operation has an _async variant. Reuse one client within a with SDK(...) or async with SDK(...) context for deterministic cleanup. Set SARJ_CALL_ID to an ID returned by an earlier call.

import asyncio
import os

from sarj_platform_sdk import SDK


async def main():
    async with SDK(
        api_key_auth=os.environ["SARJ_API_KEY"],
        timeout_ms=10_000,
    ) as sdk:
        call = await sdk.calls.get_call_async(call_id=os.environ["SARJ_CALL_ID"])
        print(call.data.status)


asyncio.run(main())

Errors, timeouts, and retries

API errors with a documented shape raise errors.ErrorResponse. Branch on exception.data.error.type and retain the request ID for support. When exception.data.meta.request_id is null, use the X-Request-ID response header. Other HTTP failures raise errors.SDKError; network failures raise HTTPX exceptions.

import os
import httpx

from sarj_platform_sdk import SDK, errors

with SDK(api_key_auth=os.environ["SARJ_API_KEY"], timeout_ms=10_000) as sdk:
    try:
        call = sdk.calls.get_call(call_id=os.environ["SARJ_CALL_ID"])
        print(call.data.status)
    except errors.ErrorResponse as exception:
        request_id = exception.data.meta.request_id or exception.headers.get("x-request-id")
        print(exception.data.error.type, request_id)
    except errors.SDKError as exception:
        print(exception.status_code, exception.headers.get("x-request-id"))
    except httpx.RequestError:
        print("Transport failed; reconcile any write before resubmitting.")

Set timeout_ms for your workload. When omitted, the SDK inherits the HTTPX client timeout: 5 seconds for SDK-created clients. A supplied client can have a different default. A method's non-null value overrides the SDK setting; None inherits it. This HTTPX timeout bounds network operations, not total retry elapsed time, call duration, or a polling loop.

Retries are disabled by default. For a read operation, opt in with the method's retries argument:

from sarj_platform_sdk import SDK
from sarj_platform_sdk.utils import BackoffStrategy, RetryConfig

with SDK(timeout_ms=10_000) as sdk:
    health = sdk.system.get_health(
        retries=RetryConfig(
            strategy="backoff",
            backoff=BackoffStrategy(
                initial_interval=100,
                max_interval=1_000,
                exponent=1.5,
                max_elapsed_time=5_000,
            ),
            retry_connection_errors=False,
        ),
    )
    print(health.data.status)

The public health check verifies reachability, not API-key validity. Opt-in retries cover HTTP 429, 500, 502, 503, and 504. retry_connection_errors=True also retries network errors and timeouts. Use retries=None to disable a client's retry policy for one operation. Backoff uses milliseconds, jitter, and a positive Retry-After when present; its elapsed-time budget is checked after failures and can be exceeded by a sleep or request. See the recovery decisions for validation, authorization, call-limit, and scheduling errors. Do not enable global retries for call creation: after a timeout, an immediate call may already exist, and retrying can place another call. Keep the returned call ID when available and reconcile the result before retrying a write.

Operations

Resource Methods Reference
sdk.system get_health Health
sdk.calls create_call, get_call Calls
sdk.calls cancel_scheduled_call, reschedule_scheduled_call Scheduling
sdk.schedule_configs create_schedule_config Retry policies

The recording endpoint redirects to binary audio and is intentionally omitted from the generated SDK. Use an authenticated HTTP client to resolve permanent_recording_url when you need a fresh download. Standalone STT/TTS services use their own endpoints and credentials; see Speech models.

Webhook payloads

Use sarj_platform_sdk.models.WebhookNotification.model_validate_json(body) to parse delivered notification JSON. Host your HTTPS receiver and validate its configured delivery credential in your application. Follow the webhook guide for acknowledgment and deduplication.

Support and compatibility

Include the request ID when contacting support@sarj.ai. This SDK is in beta; pin the version used by your application and review API documentation before upgrading.

Metadata

Release files for sarj-platform-sdk 0.4.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sarj-platform-sdk 0.4.4
File Size Uploaded Provenance Actions
sarj_platform_sdk-0.4.4.tar.gz 59.5 kB With provenance Details for sarj_platform_sdk-0.4.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sarj-platform-sdk 0.4.4
File Interpreter ABI Platform Actions
sarj_platform_sdk-0.4.4-py3-none-any.whl Python 3 none any Details for sarj_platform_sdk-0.4.4-py3-none-any.whl

Total release size: 147.3 kB

Release files / sarj_platform_sdk-0.4.4.tar.gz

Download URL sarj_platform_sdk-0.4.4.tar.gz
Size 59.5 kB
Tags Source
SHA-256 checksum
How to use checksums
074dbc51cec39e28fe9baa7fb4b17c21f281ee5c128804a94eef662056fdf834
BLAKE2b-256 checksum
How to use checksums
c38ed02ac0d8b062f4d9a649db45df75ec28bcaeb1453a84a54f9ac5bc9d47ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / sarj_platform_sdk-0.4.4-py3-none-any.whl

Download URL sarj_platform_sdk-0.4.4-py3-none-any.whl
Size 87.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed748f42ee3c6db534792651bcfd769e5d70ce83076c0c448ff09e4e0a5a1753
BLAKE2b-256 checksum
How to use checksums
08d94eb0995787cb4ffc585ecc1de425948f59640169d8fede708566c5240559
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for sarj-platform-sdk 0.4.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sarj_platform_sdk-0.4.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page