API documentation

Lumeira REST API · v1

A predictable, JSON-only REST API. Authenticate with a bearer token, paginate with limit/page, and rely on rich error objects for failures.

Base URL

api.lumeira.app/v1

Auth

Bearer lm_live_•••

Rate limit

600 req/min

Quick start

A typical product list request.

curl https://api.lumeira.app/v1/products?color=Chestnut&limit=10 \
  -H "Authorization: Bearer lm_live_••••" \
  -H "Accept: application/json"

Returns

{
  "data": [
    {
      "id": "p1",
      "name": "Mira — Chestnut Waves",
      "price": 489,
      "currency": "CAD",
      "stock": 24,
      "rating": 4.8,
      "supplier": { "id": "u-supp", "name": "Maison Hair Co." }
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 1 }
}

Auth

POST

/v1/auth/session

Create a session for a user.

DELETE

/v1/auth/session

End the current session.

GET

/v1/auth/me

Retrieve the current user.

Products

GET

/v1/products

List products with filters and pagination.

GET

/v1/products/{id}

Get a single product.

POST

/v1/products

Create a product (supplier/admin).

PATCH

/v1/products/{id}

Update a product.

DELETE

/v1/products/{id}

Archive a product.

Cart & Orders

GET

/v1/cart

Retrieve the customer's cart.

POST

/v1/cart/items

Add an item to the cart.

POST

/v1/orders

Place an order from the cart.

GET

/v1/orders/{id}

Fetch an order with line items.

PATCH

/v1/orders/{id}/status

Update fulfilment status.

AI Try-On

POST

/v1/ai/try-on

Render a composite of a wig on a user photo.

GET

/v1/ai/try-on/{jobId}

Poll a try-on job for status.

Consultations

GET

/v1/consultations

List sessions for the current user.

POST

/v1/consultations

Book a Zoom consultation.

PATCH

/v1/consultations/{id}

Reschedule or cancel a session.

Admin

GET

/v1/admin/metrics

Aggregate KPIs for the platform.

GET

/v1/admin/suppliers

List suppliers and fulfilment scores.

Errors

400

validation_error

Request body failed schema validation.

401

unauthorized

Missing or invalid bearer token.

403

forbidden

Authenticated but not allowed to perform this action.

404

not_found

Resource does not exist.

429

rate_limited

Exceeded 600 requests per minute.

500

internal_error

Something broke on our end — try again.