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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.