Lunidex Public API v1

A working integration needs a key, a server-side secret, and an HTTPS request to the API base URL.

1. 1

   Create a key

   Open the API keys card in your Lunidex dashboard. Give the key a name and choose read-only or read-and-write access. The full secret is shown once; copy it before closing the message.

2. 2

   Store the secret on your server

   Save the key as LUNIDEX_API_KEY in your hosting provider’s secret manager. Do not commit it or send it to a browser.

3. 3

   Make the first request

   Send GET /me from your backend. Private endpoints require Authorization: Bearer followed by the key.

curl --fail-with-body \
  -H "Authorization: Bearer $LUNIDEX_API_KEY" \
  https://lunidex.app/api/v1/me

const API_BASE_URL = "https://lunidex.app/api/v1";
const apiKey = process.env.LUNIDEX_API_KEY;

if (!apiKey) throw new Error("Missing LUNIDEX_API_KEY");

const response = await fetch(API_BASE_URL + "/me", {
  headers: { Authorization: "Bearer " + apiKey },
});
const result = await response.json();

if (!response.ok) {
  throw new Error(result.error?.code ?? "REQUEST_FAILED");
}

console.log(result.data);

Send the key in the HTTP Authorization header for every private /api/v1 request. The API returns JSON in a data envelope; private responses use Cache-Control: private, no-store.

The API sees only data synced to the Lunidex account in Neon. Data that exists only on a device is not available. Account identity omits the email address.

List endpoints return data plus meta.nextCursor. Pass that cursor unchanged to request the next page, and stop when it is null.

• The default page size is 25 and the maximum is 100. Catalogue search is fixed at 24 results per page.
• Cards accept language and set filters. Sealed positions accept language and productId; transactions accept language, productId, type, includeVoided, and voided. Catalogue search accepts q and cursor.
• A cursor can become stale when the collection, journal, prices, or filters change. The API returns 409; start again without the cursor and use the latest state.

const API_BASE_URL = "https://lunidex.app/api/v1";
const apiKey = process.env.LUNIDEX_API_KEY;
let cursor = null;

if (!apiKey) throw new Error("Missing LUNIDEX_API_KEY");

do {
  const query = new URLSearchParams({ limit: "100" });
  if (cursor) query.set("cursor", cursor);

  const response = await fetch(API_BASE_URL + "/cards?" + query, {
    headers: { Authorization: "Bearer " + apiKey },
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error?.code ?? "REQUEST_FAILED");

  console.log(result.data);
  cursor = result.meta?.nextCursor ?? null;
} while (cursor);

Paths are relative to the API base URL. Each row shows required access and the parameters listed in the OpenAPI contract. Open the machine-readable specification for full schemas, request and response examples, and operation errors; the sections below provide the human-readable guide.

GET /cards lists owned variants without loading the full TCGdex catalogue. Each holding includes cardId, setId, language, variant, and quantity; the optional list filters are language and set.

GET /cards/{cardId} returns useful TCGdex metadata and holdings for a card in this account. Add the language query parameter to narrow the holdings.

{
  "language": "en",
  "variant": "reverse",
  "quantity": 2
}

Older holdings without a language remain visible; their language can be null and they may be marked legacy.

Card valuations are never returned by this API.

Sealed positions include quantities by language, cost, and current value from prices already stored in Lunidex. Amounts are integer EUR cents. A missing current price is null and is identified by missingPrice; the summary also reports missingPrices.

In GET /summary, the sealed value is null if any held product has no price; missingPrices gives the count.

Success responses use { "data": ..., "meta": ... } (meta is optional). Errors use { "error": { "code": ..., "message": ..., "details": ... } } (details is optional).

Common responses: 400 invalid transaction data; 401 invalid key; 403 insufficient permission; 404 missing or unowned resource; 409 stale cursor or revision; 410 account being deleted; 422 invalid query or request body; 429 quota; 500 unexpected server error; 502 card data unavailable; and 503 API unavailable.

All private API responses use Cache-Control: private, no-store. The public OpenAPI document is served separately at /api/v1/openapi.json.

Limits are applied per Lunidex account and shared by its API keys.

Card details and sealed calculations also share separate global ceilings of 5,000 operations per day per category. A 429 response includes Retry-After.