Developers
API quickstart
Make your first call, then the rules every request follows: errors, limits, and pagination.
The Lumina Sales REST API runs the same account operations as the dashboard. This page gets you to a first successful call, then covers the rules every request follows. For every endpoint and its fields, see the REST API reference.
Your first call
- As the agency owner, create a token with Read the account at app.luminasales.io/developers/api. See Access tokens.
- Put it in an environment variable, not in your code:
export LUMINA_ACCESS_TOKEN="lsk_live_..."- Ask for your agency:
curl "https://luminasales.io/api/v1/agency" \
-H "Authorization: Bearer $LUMINA_ACCESS_TOKEN"You get back your agency and your permissions, wrapped like this:
{
"data": { "...": "..." },
"request_id": "6f1c2c1e-..."
}- List your clients:
curl "https://luminasales.io/api/v1/clients?limit=10" \
-H "Authorization: Bearer $LUMINA_ACCESS_TOKEN"- Create one (needs a token with Change the account):
curl -X POST "https://luminasales.io/api/v1/clients" \
-H "Authorization: Bearer $LUMINA_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-client-riverside-001" \
-d '{"business_name": "Riverside Dental", "contact_name": "Dana Ruiz", "email": "dana@example.com"}'Creating a client also creates their onboarding form, like Add a client in the dashboard.
Basics
| Base URL | https://luminasales.io/api/v1 |
| Auth | Authorization: Bearer lsk_live_... |
| Format | JSON in and out. Send Content-Type: application/json on requests with a body. |
| Body size | Up to 1 MiB for most operations, less for some (for example 16 KB for blog generation), except file uploads |
| OpenAPI | https://luminasales.io/api/v1/openapi.json (OpenAPI 3.0.3, public) |
| Status | docs.luminasales.io/status, or GET https://luminasales.io/api/status for JSON |
Import the OpenAPI file into Postman, Insomnia, or a code generator to get every operation and schema.
Requests
- Unknown fields are rejected. Send only fields the reference lists.
PATCHchanges only what you send. Sendingnullclears a field.PUTreplaces the whole resource.POSTthat creates something returns201. Everything else that succeeds returns200.- Every response carries an
X-Request-Idheader. Include it when you contact support.
Responses
A single record:
{ "data": { "id": "…" }, "request_id": "…" }A list:
{
"data": { "items": [], "total": 42, "limit": 25, "offset": 0 },
"request_id": "…"
}Your code should accept new fields and new enum values appearing over time. Breaking changes would come with a new version in the path; this is v1.
Pagination
List endpoints take limit (1–100, default 25) and offset (0–100000). Results come newest first. Keep asking for the next page while offset + limit < total.
curl "https://luminasales.io/api/v1/clients?limit=100&offset=100" \
-H "Authorization: Bearer $LUMINA_ACCESS_TOKEN"Idempotency
Network calls fail halfway. To retry a POST safely, send an Idempotency-Key header:
- 8 to 200 printable characters. A UUID works well.
- Only on
POSTrequests with a JSON body. - Lumina remembers the key for 24 hours, per member.
| Retry with… | Result |
|---|---|
| The same key and the same body | The original response again, with Idempotency-Replayed: true. Nothing runs twice. |
| The same key and a different body or path | 409 idempotency_conflict |
| The same key while the first request is still running, or after it failed with a 5xx | 409 request_in_progress. If the first call may still be running, wait and retry with the same key: once it finishes, you get its response. |
If you got a 5xx back after the request started, its key stays locked for 24 hours and a retry with it gets 409 request_in_progress. Read the resource to see whether the change happened, and retry with a new key only if it did not. Do not switch keys while the first call might still be running, or the work can happen twice. A 503 from sign-in checks or rate limiting fails before anything starts, so retrying that one with the same key is safe.
Rate limits
120 requests per minute for each member of each agency. Every response shows RateLimit-Limit and RateLimit-Remaining. Over the limit you get 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry.
MCP tool calls count against the same limit.
Errors
Every error has the same shape:
{
"error": {
"code": "validation_error",
"message": "Human-readable explanation.",
"details": [{ "path": "email", "message": "Invalid email" }]
},
"request_id": "…"
}Branch on code, not on message. The most common ones:
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_json | Send a valid JSON body. |
| 401 | unauthorized | Send the Authorization: Bearer header. |
| 401 | invalid_token | The token is wrong, expired, or revoked. Make a new one. |
| 402 | subscription_required | The agency's plan is not active. The owner needs to fix billing. |
| 403 | insufficient_scope | The token lacks the scope. Make a token with it. |
| 403 | insufficient_permissions | The token's creator lacks the permission for this area. |
| 403 | owner_required | Owner-only operation. |
| 403 | owner_action_required | Tokens can never do this. Use the dashboard. |
| 403 | token_agency_mismatch | You sent X-Lumina-Agency-Id for a different agency. Remove it. |
| 403 or 503 | feature_unavailable | The feature (for example Landers) is not switched on for the agency (403), or not available right now (503). |
| 404 | not_found | No such record in this agency. |
| 405 | method_not_allowed | Wrong method. The Allow header lists the right ones. |
| 409 | setup_required | The owner has not finished setting up the agency. |
| 409 | conflict | Something with that unique value already exists. |
| 409 | slot_confirmation_required | Publishing needs a paid demo slot. Buy it in the dashboard, as the owner or a member who can manage Demos & landers. |
| 409 | subdomain_required | Claim a subdomain before this (for example embeds). |
| 409 | idempotency_conflict, request_in_progress | See Idempotency above. |
| 413 | body_too_large, file_too_large | Send less. |
| 415 | unsupported_media_type | Send Content-Type: application/json. |
| 422 | validation_error | Fix the fields listed in details. |
| 422 | operation_rejected | The dashboard would have refused this too. The message says why. |
| 422 | invalid_resource | A referenced record does not exist or a value is out of range. |
| 429 | rate_limited | Wait for Retry-After. |
| 500 | internal_error | Retry later. Send us the request_id if it continues. |
| 503 | service_unavailable, rate_limit_unavailable, auth_unavailable and other *_unavailable codes | A dependency is down. Check status and retry. |
There are also codes for specific resources, like invalid_node on demos and invalid_origins on embeds. The REST API reference lists them per operation.
Example in TypeScript
const BASE = "https://luminasales.io/api/v1";
async function lumina<T>(path: string, init: RequestInit = {}): Promise<T> {
const response = await fetch(`${BASE}${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.LUMINA_ACCESS_TOKEN}`,
"Content-Type": "application/json",
...init.headers,
},
});
if (response.status === 429) {
const wait = Number(response.headers.get("Retry-After") ?? "5");
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
return lumina<T>(path, init);
}
const body = await response.json();
if (!response.ok) {
throw new Error(`${body.error.code}: ${body.error.message} (request ${body.request_id})`);
}
return body.data as T;
}
const agency = await lumina<Record<string, unknown>>("/agency");
console.log(agency);Run it on a server. Never ship a token to a browser.
If something goes wrong
- Auth, permission, rate limit, and connection problems: API and MCP.
- Every operation and its fields: REST API reference.
Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.
