Public API

The Open Stamp Commons API

Every catalog record, registry, and resolver lookup is available over a plain JSON API at /api/v1. The data is CC0; the website is free to browse anonymously. Reading through this API requires a signed-in session, and API keys for programmatic access are part of a paid plan (Collector and up).

Authentication

Every endpoint, read or write, requires an authenticated actor: a signed-in session or an API key sent as an Authorization: Bearer osc_live_… header. Anonymous requests get a 401 — the free, anonymous read path is the server-rendered website, not this API. API keys for programmatic access are part of a paid plan (Collector and up); keys add capacity, never access.

Rate limits

Because every request is authenticated, limits apply per account rather than per IP: standard keys share one window, and Developer and Commercial keys get a higher-volume window. When a limit is exceeded the API returns 429 with a Retry-After header. Limits protect the service; they are never used to gate the data.

Errors

Errors are JSON objects with a single error message and a conventional status code: 400 for malformed input, 401 for missing authentication, 404 for unknown records, 429 for rate limits.

Get a record

Fetch a single record by its OSID, including its current version, full version history, votes, and provenance.

GET/api/v1/records/{osid}

Path parameters

osidstring · requiredA well-formed OSID, e.g. US-1954-3c-0001. Returns 404 for unknown identifiers.
Request
curl https://openstampcommons.org/api/v1/records/US-1954-3c-0001 \
  -H "Authorization: Bearer osc_live_…"
200 · Response (abridged)
{
  "osid": "US-1954-3c-0001",
  "status": "VERIFIED",
  "country_code": "US",
  "year_issued": 1954,
  "denomination_encoded": "3c",
  "versions": [ … ],
  "votes": [ … ]
}

Search records

List and search the catalog with filters and offset pagination.

GET/api/v1/records

Query parameters

qstringFree-text search across descriptions and series.
countrystringTwo-letter OSID country code, e.g. US.
yearintegerYear of issue.
statusstringLifecycle status, e.g. VERIFIED or DISPUTED.
limitinteger · ≤ 100Page size. Defaults to 48.
offsetintegerZero-based offset for pagination.
Request
curl "https://openstampcommons.org/api/v1/records?country=US&year=1954&limit=10" \
  -H "Authorization: Bearer osc_live_…"
200 · Response (abridged)
{
  "records": [ … ],
  "total": 412,
  "limit": 10,
  "offset": 0
}

Resolve an OSID

The permanent resolver lives at /id/{osid}. It resolves every OSID ever assigned — deprecated records redirect to their canonical successor. The resolver is plain HTML by design so a citation works in any browser, for decades to come.

GET/id/{osid}
Always CC0

Every field these endpoints return is public-domain data. No attribution is required, though a link back to the OSID resolver is appreciated. Rate limits apply to protect the service, never to gate the data.