Stravax Engage ships a REST API (v1) for tenant integrations. It is authenticated with an API key from Settings > Developer. Sending uses the same pipeline as the agent inbox, so delivery, consent, billing, and window rules stay the same.
The machine-readable contract is available at /api/v1/openapi.json. This guide remains the task-oriented companion.
Send your API key as a bearer token in the Authorization header:
Authorization: Bearer <your-api-key>
The key determines which organization the request belongs to, you never pass an organization id yourself. A key from one organization has no visibility into another organization's contacts, messages, or resources.
The same thing that happens in the inbox: if the contact's session window has expired, the API returns the identical error the inbox's session route would return for the same contact. There's no separate error format to learn for API sends versus inbox sends.
Yes. Sending a marketing template to a contact who hasn't opted in is blocked, the same as it would be from the inbox, rather than silently allowed because the request came from your own system.
Yes, at two levels: a per-key request rate limit, and a monthly request ceiling included in your plan. Going over either returns an error rather than queueing or degrading silently. See current plans for the specific numbers on your plan, and upgrade in-app if you need more headroom.
Keys are created, viewed, and revoked from Settings > Developer. See API keys for how scopes and revocation work, and Outbound webhooks if you also want Stravax Engage to push events to your systems instead of only pulling and pushing through this API.
List responses contain next_cursor. Pass it as cursor to continue, and keep going until it comes back null, which is the only reliable end-of-list signal: a page may be shorter than your limit and still have more after it. limit defaults to 100 and cannot be greater than 100 (a larger value is refused rather than quietly reduced). A cursor is opaque, so read it only as a value to hand back.
Two page sizes are set by the product rather than by you. A conversation's messages come back at most 50 at a time, whatever limit you ask for, because that is the page size the agent inbox itself reads. Conversations are listed channel by channel, newest activity first within each channel, rather than as one merged timeline across every connected number.
Send Idempotency-Key on every write. For 24 hours, a replay identity is your organization, the API operation, the API key that made the call, and the key value. A repeated completed request with that same identity returns its first stored response, even if the retry body differs. Use a fresh key for a new logical operation.
Each API operation explicitly marks only its own refusals that happened before any durable write as releasable, so you can correct that request and retry with the same key. A not_found code is not globally releasable: the note route releases its visibility refusal before its insert, while a contact upsert's post-insert re-read miss is stored and replayed. Other claims are retained. If an original request stops after its claim is stored but before its response is saved, the same identity can return 409 idempotent_replay_pending for up to 24 hours. A nightly reaper removes expired replay rows, but never takes over a pending request because retrying its side effect could send or create it twice. On a quiet night it exits after its first short page; under sustained load it continues only within a 20-second wall-clock budget.
Every v1 response contains X-Request-Id. You may provide one and it is echoed back, which helps support trace a failed call without sharing request content.