Skip to main content
sarj-platform-sdk supports Python 3.10+ and defaults to https://platform-api.sarj.ai/api/v1.

Install

Store SARJ_API_KEY in your environment or a secret manager. Set SARJ_SCENARIO_ID to an active dashboard scenario UUID and TEST_PHONE_NUMBER to an intended recipient.

Create and inspect a call

create_call returns on acceptance. Save created.data.id; fetch it again or use webhooks. Reports arrive asynchronously and may remain null permanently; the response reference explains eligibility and recording availability. Bound polling by elapsed time. with SDK(...) and async with SDK(...) close clients owned by the SDK. There are no public close() or aclose() methods. Your application owns supplied HTTPX client= or async_client= instances and must close them. Reuse the SDK within its context.

Async calls

Await each operation’s _async variant:
Set SARJ_CALL_ID to a returned call ID. In an existing event loop, use await main() instead of asyncio.run().

Schedule a call

Scheduling requires SDK 0.4.0 or newer. Check PyPI for availability; use the REST reference until that version is published. Compute scheduled_at as a timezone-aware datetime when sending: 10 minutes to 30 days ahead. Policy timezone belongs beside retry_window, not inside it. Omit scheduled_at or pass None for an immediate call. Validate untyped input: {} can be treated as an omitted timestamp.
max_retries=2 permits up to two policy retries after eligible unsuccessful outcomes; infrastructure failure redials do not consume this budget. Policy expiry is one hour to seven days. Scheduling must be enabled for your organization/deployment (scheduling_disabled). Cancel or reschedule only while pending; after release for dialing, expect 409 call_not_pending. Infrastructure redials use a separate delay and bypass policy windows and expiry; the seven-day platform ceiling still applies. For call.data.booking_outcome of rescheduled_existing or kept_existing, use the returned ID and time: they identify an existing pending booking for the same scenario and number. Omitted schedule_config_id uses the scenario’s default policy, if configured. Save policy IDs: the policy API is create-only (no fetch, list, update, or disable). Set SARJ_CALL_ID to the returned booking ID. These actions are alternatives; cancelling after rescheduling cancels the moved booking:

Errors, timeouts, and retries

Branch on error.type, retain the request ID, and handle HTTPX failures separately. Unknown HTTP response shapes can raise SDKError. If meta.request_id is null, as with some authentication rejections, use X-Request-ID. timeout_ms sets a per-request HTTPX network timeout in milliseconds. Without an SDK setting, it inherits the HTTPX client’s timeout: 5 seconds for clients created by the SDK; supplied clients may differ. A method’s non-null timeout_ms overrides the SDK setting; None inherits it. Set an explicit workload timeout. It does not bound total retries, call duration, or polling. HTTP retries are off by default. Enabled retries cover 429, 500, 502, 503, 504; retry_connection_errors=True also covers HTTPX network errors and timeouts. Method retries= overrides client retry_config=; retries=None disables that method’s retries. Configure reads individually:
Backoff intervals and max_elapsed_time use milliseconds. The SDK honors positive Retry-After; otherwise it jitters exponential backoff. max_elapsed_time is checked after failed attempts, so a sleep or request can exceed it. Use an application deadline to bound total time. Immediate create_call requests have no documented idempotency guarantee. After a timeout or connection loss, the call may already be accepted; reconcile before resubmitting to avoid duplicate calls. HTTP retries and scheduled dial retries are separate.

Resources

Last modified on October 27, 2026