FAQs
Short answers to the questions developers ask most often, with links to the full explanation.
Is there a free sandbox?
Yes. Test keys (rai_test_...) use test mode: nothing is dialled, nothing is charged, and every object has "livemode": false. Calls are simulated, and the destination number chooses the outcome (+12025550100 completes, +12025550101 is not answered, and so on), with a fixture transcript, a short synthetic recording and analysis. Test mode also has a built-in Sample agent and sample number, so you can try everything before your own agent is ready. Compliance rules apply in test mode too. See Test mode.
Is the API generally available?
Not yet. The API is in private preview and is enabled per workspace by RelationsAI; a workspace that has not been enabled answers 403 api_access_not_enabled. Webhook delivery is in preview too and can be unavailable even when the API is enabled: check capabilities.webhooks on GET /workspace. To request access, write to support@relationsai.com. Operations marked Preview in the API reference are the most likely to change before general availability. See API availability.
Will the API change under me?
Additive changes (new operations, fields, enum values, event types and error codes) ship without a new version and are listed in the changelog. Write your code to tolerate them: ignore unknown fields and treat unknown enum values as "other". Breaking changes need a new major version in the path and at least six months' notice. Events carry an api_version.
Can I create agents through the API?
Not yet. Agents are created, configured and published in the console; the API reads them and checks their readiness. Creating and editing agents through the API is planned for a later version. See Creating and preparing agents.
Can I hang up a call, receive inbound calls or read a transcript during the call?
Not through the API today. The workspace object reports these as capabilities (end_call, inbound_calls, live_transcript, all false today), so your code can check instead of assuming. Transcripts are available after the call ends; inbound calls do not appear in the call list.
Does the analysis include sentiment?
No. Analysis has a summary, the fields the agent is configured to extract, and whether the goal was met. capabilities.sentiment_analysis is false. See Working with analysis results.
Can I use the API from a browser?
Test keys only, for experimentation (the docs' API explorer accepts test keys only). Live keys are refused from browsers with 403 live_key_not_allowed_in_browser: a key in browser code is visible to anyone who opens the page. Call the API from your server.
How do I avoid placing a call twice?
Every request is executed, so do not resend a call blindly. Put your own id in metadata, and if you did not see the answer, list calls with to and created_after and look for it before sending again. For extra safety, send an optional Idempotency-Key and reuse it on every retry of that call: a retry of a request that already succeeded then returns the original response instead of placing another call. See Idempotency and Retry and reliability practices.
My request timed out. Was the call placed?
Maybe. Check before sending it again: list calls with to and created_after and look for your metadata. If you sent an idempotency key, you can instead resend the same request with the same key: if the first attempt went through you get its response back (with Idempotent-Replayed: true). Never assume a timed-out request had no effect.
Why does POST /calls answer 202 and not 200?
Because the call happens after your request returns. 202 means the call passed every check and was handed over to be placed. The result comes later through call.ended and call.settled, or by reading the call. See Making an outbound call.
When are the transcript, recording and analysis ready?
After the call ends; wait for call.settled, which means everything is final, including the charge. In test mode that is about 30 seconds after the call is created. In live mode artifacts are usually ready within a minute, sometimes several minutes later.
Why do I get 404 for an id I just used?
Usually the mode: test and live data are completely separate, so an id created with a test key is not found with a live key, and the reverse. The API answers 404 resource_not_found for ids from another mode or workspace, exactly as for ids that do not exist. See Troubleshooting.
Can API keys turn off the do-not-call list or consent checks?
No. The do-not-call list, consent, calling hours and the per-number daily limit are applied to every call and every campaign start and resume, and no key, scope or request option can switch them off. The API also refuses to start or resume a campaign whose do-not-call screening a person switched off in the console (409 campaign_dnc_override_enabled). One timing detail: a campaign that is already running is not re-checked before each call, so a number added to the list mid-run is applied when you pause and resume the campaign, or stop it. Compliance settings are changed by admins in the console. See Consent and DNC.
Can I manage API keys through the API?
No. Keys are created, rotated and revoked by workspace admins in the platform, under Settings → API Keys (Get an API key). The API can tell you about the key you are using (GET/workspace), never create one.
Are webhooks delivered in order, and exactly once?
No to both. Delivery is at least once and unordered. Deduplicate by the event id, and never let an older snapshot overwrite newer state. Failed deliveries are retried for about a day, longer when your endpoint keeps failing: after 5 failures in a row it is paused (up to an hour at a time) without using up the deliveries' attempts. See Receiving webhooks.
Is there an endpoint that lists past events?
Not in v1. To troubleshoot, use the delivery log of each endpoint (kept for 30 days) and redeliver failed deliveries. To catch up after an outage, reconcile with the list endpoints (calls, campaigns, recipients), which always reflect the current state.
How much does a call cost?
Live calls are charged per started minute of talk time at your workspace rate, from the workspace balance; a call that is not answered is not charged. Each call reports billable_minutes and cost (in minor units of the workspace currency) once settled. Test mode never charges. Rates and balance are managed in the console.
Are there official SDKs?
Not today. The API is plain HTTPS and JSON, and every guide has complete examples for cURL, Node.js and Python. The OpenAPI 3.1 document is published at /openapi.json and /openapi.yaml if you want to generate a client.
Is there a status page?
There is no public status page. If the API is unavailable you get 503 service_unavailable with Retry-After; if a problem lasts more than a few minutes, write to support@relationsai.com with request ids. See Status.
How do I get help?
Write to support@relationsai.com with the request_id of a failing request, the time in UTC, the operation and the mode. Never send API keys or full Authorization headers, webhook signing secrets, recording links, customer personal data (names, phone numbers, contact details) or transcripts, recordings and analysis of real calls; send ids (key_..., call_...) instead. See Support.