API Overview
Base URLs, authentication, pagination, idempotency, rate limits, and SDK setup for the RevKeen API.
The RevKeen API is organized around a single REST surface for payments, billing, subscriptions, invoicing, usage, and terminal workflows. Use this page for the platform-wide rules. Use the interactive API reference for endpoint-by-endpoint details.
Start Here
Production Base URL
https://api.revkeen.com/v2
Staging Base URL
https://staging-api.revkeen.com/v2
Auth Header
Send your API key in x-api-key. Production uses rk_live_*; staging uses rk_sandbox_*.
Mock Server
https://mock-api.revkeen.com/v2 on the Hetzner-hosted Scalar mock stack. No persistence, no side effects.
Base URLs
| Environment | Base URL | Purpose | Notes |
|---|---|---|---|
| Production | https://api.revkeen.com/v2 | Live traffic and real transactions | Use rk_live_* keys |
| Staging | https://staging-api.revkeen.com/v2 | Integration testing and pre-production validation | Use rk_sandbox_* keys |
| Mock | https://mock-api.revkeen.com/v2 | Schema validation, client prototyping, CI smoke checks | Auth not enforced |
Staging is the recommended environment for integration work. It is isolated from production, but the API key prefix remains rk_sandbox_* in the current platform implementation.
Authentication
All authenticated requests use the x-api-key header:
x-api-key: rk_sandbox_your_api_keyDo not use Authorization: Bearer for the public REST API.
| Key Prefix | Environment | Typical Use |
|---|---|---|
rk_live_* | Production | Real customers, real money, production automations |
rk_sandbox_* | Staging | QA, integration development, test data, demo accounts |
curl https://staging-api.revkeen.com/v2/customers \
-H "x-api-key: rk_sandbox_your_api_key" \
-H "Accept: application/json"See Authentication for scopes, key hygiene, and security guidance.
OpenAPI JSON
The public OpenAPI artifact used by the docs is available at:
https://docs.revkeen.com/api/openapi-specUse it when importing the API into Scalar, Postman, Insomnia, Bruno, or other OpenAPI-aware tools.
/api/openapi-spec is the public, machine-readable spec route. It is intended for tooling imports and the Scalar reference, not as a narrative documentation page.
Pagination
RevKeen uses cursor-based pagination on list endpoints.
Request Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Number of items to return per request. Max 100. |
starting_after | string | - | Cursor for the next page, using the last item ID from the previous response. |
ending_before | string | - | Cursor for the previous page, using the first item ID from the current response. |
Response Shape
{
"object": "list",
"data": [],
"has_more": false,
"url": "/v2/customers"
}| Field | Description |
|---|---|
data | The current page of records |
has_more | true when another page exists |
url | The canonical collection path |
Idempotency
Use Idempotency-Key on write requests that create or mutate financial state:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000- Use a fresh UUID per logical operation.
- Reuse the same key only when retrying the same request.
- RevKeen honors idempotency keys for 24 hours.
Rate Limits
| Environment | Limit | Applies To |
|---|---|---|
| Production | 1,000 requests/minute | Authenticated API traffic per API key |
| Staging | 100 requests/minute | Authenticated API traffic per API key |
| Mock | 30 requests/second per IP | Hosted Scalar mock server traffic |
When a limit is exceeded, the API returns 429 Too Many Requests and includes Retry-After. Authenticated API responses also include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
SDK Quickstart
All official SDKs can target staging by overriding the base URL.
import RevKeen from '@revkeen/sdk';
const client = new RevKeen({
apiKey: process.env.REVKEEN_API_KEY,
baseUrl: 'https://staging-api.revkeen.com',
});from revkeen import RevKeen
import os
client = RevKeen(
api_key=os.environ["REVKEEN_API_KEY"],
base_url="https://staging-api.revkeen.com",
)use RevKeen\Client;
use RevKeen\ClientOptions;
$client = new Client(
apiKey: getenv('REVKEEN_API_KEY'),
options: new ClientOptions(
baseUrl: 'https://staging-api.revkeen.com',
)
);See the full SDK guides for language-specific examples and production configuration.