Skip to content

Popular

  • Embed not showing on my website
  • Connect Claude or ChatGPT (MCP)
  • Set up a custom domain
  • Order a build through Lumina
  • What Lumina Assistant can do

↑ ↓ to move · Enter to open · Esc to close

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

  1. As the agency owner, create a token with Read the account at app.luminasales.io/developers/api. See Access tokens.
  2. Put it in an environment variable, not in your code:
bash
export LUMINA_ACCESS_TOKEN="lsk_live_..."
  1. Ask for your agency:
bash
curl "https://luminasales.io/api/v1/agency" \
  -H "Authorization: Bearer $LUMINA_ACCESS_TOKEN"

You get back your agency and your permissions, wrapped like this:

json
{
  "data": { "...": "..." },
  "request_id": "6f1c2c1e-..."
}
  1. List your clients:
bash
curl "https://luminasales.io/api/v1/clients?limit=10" \
  -H "Authorization: Bearer $LUMINA_ACCESS_TOKEN"
  1. Create one (needs a token with Change the account):
bash
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 URLhttps://luminasales.io/api/v1
AuthAuthorization: Bearer lsk_live_...
FormatJSON in and out. Send Content-Type: application/json on requests with a body.
Body sizeUp to 1 MiB for most operations, less for some (for example 16 KB for blog generation), except file uploads
OpenAPIhttps://luminasales.io/api/v1/openapi.json (OpenAPI 3.0.3, public)
Statusdocs.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.
  • PATCH changes only what you send. Sending null clears a field.
  • PUT replaces the whole resource.
  • POST that creates something returns 201. Everything else that succeeds returns 200.
  • Every response carries an X-Request-Id header. Include it when you contact support.

Responses

A single record:

json
{ "data": { "id": "…" }, "request_id": "…" }

A list:

json
{
  "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.

bash
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 POST requests with a JSON body.
  • Lumina remembers the key for 24 hours, per member.
Retry with…Result
The same key and the same bodyThe original response again, with Idempotency-Replayed: true. Nothing runs twice.
The same key and a different body or path409 idempotency_conflict
The same key while the first request is still running, or after it failed with a 5xx409 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:

json
{
  "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:

StatusCodeWhat to do
400invalid_jsonSend a valid JSON body.
401unauthorizedSend the Authorization: Bearer header.
401invalid_tokenThe token is wrong, expired, or revoked. Make a new one.
402subscription_requiredThe agency's plan is not active. The owner needs to fix billing.
403insufficient_scopeThe token lacks the scope. Make a token with it.
403insufficient_permissionsThe token's creator lacks the permission for this area.
403owner_requiredOwner-only operation.
403owner_action_requiredTokens can never do this. Use the dashboard.
403token_agency_mismatchYou sent X-Lumina-Agency-Id for a different agency. Remove it.
403 or 503feature_unavailableThe feature (for example Landers) is not switched on for the agency (403), or not available right now (503).
404not_foundNo such record in this agency.
405method_not_allowedWrong method. The Allow header lists the right ones.
409setup_requiredThe owner has not finished setting up the agency.
409conflictSomething with that unique value already exists.
409slot_confirmation_requiredPublishing needs a paid demo slot. Buy it in the dashboard, as the owner or a member who can manage Demos & landers.
409subdomain_requiredClaim a subdomain before this (for example embeds).
409idempotency_conflict, request_in_progressSee Idempotency above.
413body_too_large, file_too_largeSend less.
415unsupported_media_typeSend Content-Type: application/json.
422validation_errorFix the fields listed in details.
422operation_rejectedThe dashboard would have refused this too. The message says why.
422invalid_resourceA referenced record does not exist or a value is out of range.
429rate_limitedWait for Retry-After.
500internal_errorRetry later. Send us the request_id if it continues.
503service_unavailable, rate_limit_unavailable, auth_unavailable and other *_unavailable codesA 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

ts
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

Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.