Introduction
The Ránṣẹ́ API is REST over HTTPS with JSON request and response bodies. No SDK is required.
Base URL
All requests go to the following base URL over HTTPS. HTTP is not supported.
https://api.raanse.comAuthentication
Authenticate with your API key as a bearer token:
Authorization: Bearer rk_your_api_keyYou can also send the key in an X-Api-Key header. Create and scope keys under API keys.
Response envelope
Every response is wrapped in a consistent envelope. Read the payload from data:
{
"success": true,
"message": "OK",
"statusCode": 200,
"data": { }
}On failure, success is false and error carries a machine-readable code and a human message.
Response codes
| Status | Meaning |
|---|---|
200 | Successful request. |
201 | Resource created (e.g. an accepted send). |
400 / 422 | Validation failed — check the parameters. |
401 | Missing or invalid API key. |
403 | The key is valid but not allowed to do this (scope). |
404 | The resource was not found. |
429 | Rate limit exceeded. |
5xx | Something went wrong on our side. |
Idempotency
Send an Idempotency-Key header on POST /v1/messages. A retry with the same key returns the original message instead of sending twice — safe for OTPs, receipts, and network retries.
Rate limits
Sending is rate-limited per API key (configurable per key). Exceeding the limit returns 429. Unauthenticated auth endpoints are also throttled per IP.