Quickstart

Every route is under https://collection.id/api/v1. Requests and responses are JSON; errors are problem documents with a stable code. The whole API is described by its OpenAPI 3.1 document at /api/v1/openapi.json, which any OpenAPI tool can read.

Public routes need no credentials. Search the catalog for an issue:

curl 'https://collection.id/api/v1/public/catalog/search?q=saga%201'

The answer lists matching issues and series (shortened here to the first issue; it’s a real answer). Issue pages live at https://collection.id plus the href.

{
  "q": "saga 1",
  "issues": [
    {
      "id": "a90cb734-ba4f-464c-9f9e-664cdd2605e0",
      "href": "/catalog/series/saga-2012/1",
      "seriesTitle": "Saga",
      "seriesStartYear": 2012,
      "publisher": "Image",
      "number": "1",
      "title": null,
      "coverDate": "2012-03-01",
      "coverUrl": "https://covers.collection.id/catalog/saga-2012/1-aea9491715/w800.webp?exp=…&sig=…",
      "isKey": true,
      "keyNote": "1st appearance of Alana",
      "provisional": false
    }
  ],
  "series": []
}

Cover URLs are signed and expire; fetch the issue again for a fresh one rather than storing them. Every response also carries an X-Request-Id header: quote it if you contact us about a request.

@collector/sdk is a typed client generated from the same document: every operation is a method named by its operationId, with typed inputs and results, retries and problem errors.

import { createCollectorClient } from '@collector/sdk';

const collector = createCollectorClient();

// Public routes need no credentials.
const { issues, series } = await collector.searchPublicCatalog({ query: { q: 'saga 1' } });

for (const issue of issues.slice(0, 5)) {
  console.log(`${issue.seriesTitle} #${issue.number}`, `https://collection.id${issue.href}`);
}
console.log(`${series.length} series match`);

Routes that read or change someone’s collection, a shop or the catalog need credentials. How to send them, and what each route needs, is in Authentication and scopes.

• The API reference: every operation, with “Try it” on the public ones.
• Errors: the problem format and every code.
• Retries and idempotency: making writes safe to retry.