Developers

Everything the catalogue knows is available as JSON. The public endpoints need no key, no account and no Authorization header; the catalogue is meant to be read.

Quickstart

Find a type by name or catalogue number:

curl -s 'https://api.restrike.co/v1/types?q=krugerrand&pageSize=5'

Read one type in full, issues included:

curl -s 'https://api.restrike.co/v1/types/south-africa/krugerrand/1-ounce'

Price its fine gold at spot, and convert:

curl -s 'https://api.restrike.co/v1/spot'
curl -s 'https://api.restrike.co/v1/rates'

Walk a country's coinage:

curl -s 'https://api.restrike.co/v1/issuers/south-africa'
curl -s 'https://api.restrike.co/v1/issuers/south-africa/series'
curl -s 'https://api.restrike.co/v1/types?issuer=south-africa&sort=weight_desc&pageSize=50'

When to reach for this API

It answers structured questions about a specific gold coin, which is a narrower job than it sounds and the one thing it does better than a search engine:

• Resolve a coin to its specification. GET /types?q=<name or KM#> does the lookup and gives you back fields, not prose: fine gold in grams, fineness, gross weight, diameter, thickness, years.
• Compare two coins on the same axes. Every type here is described to one specification, which is the entire premise of the catalogue. Two GET /types/{issuer}/{series}/{type} responses are directly comparable field by field with no translation step.
• Melt value. GET /spot publishes the gold price this site prices with, per gram and per troy ounce; multiply a type's fineWeight by pricePerGram. GET /rates converts USD into another display currency off the same ECB table the pages use, so your numbers and ours agree.
• Read a year table. A type response carries every issue: year, mint letter, finish, mintage, variety and marks.
• Enumerate a catalogue. Issuer → series → types, paginated, and GET /mints/{mint} for everything one mint strikes.

Do not reach for it to value a specific coin (numismatic premiums are not modelled), to grade or authenticate one, to look up anything about a specific physical coin (provenance, slab numbers), or to transact: nothing here buys or sells.

Endpoints

The /machines, /fractions and /wallet groups belong to the pull machines and are documented in the OpenAPI document; /wallet answers 401 to anyone without a session.

Versioning and deprecation

The current version is v1, at https://api.restrike.co/v1. Build against the prefixed URL.

The same paths also answer without the prefix (https://api.restrike.co/types) as a permanent alias for whatever the current version happens to be. That is convenient for a quick curl and wrong to pin an integration to, because it moves when the current version moves.

Inside a version the rules are:

• Changes are additive only: new endpoints, new optional parameters, new fields on a response.
• A field is never removed, renamed or retyped, and a code in error is never repurposed.
• A breaking change ships as a new prefix (/v2), served alongside the old one.

When a version starts winding down, every response it serves carries Deprecation: true (RFC 9745) and Sunset: <HTTP-date> (RFC 8594) (the date after which it stops answering, never less than six months out), plus a Link header with rel="successor-version" pointing at the replacement. X-API-Version names the serving version on every response, deprecated or not, so a client can assert it is talking to what it thinks it is.

Rate limits

Public callers get 600 requests per 60 seconds. Every response carries the budget so you can pace yourself rather than discover the ceiling:

RateLimit-Limit: 600
RateLimit-Remaining: 573
RateLimit-Reset: 41
RateLimit-Policy: 600;w=60;policy="public"

RateLimit-Reset is seconds until the window rolls. A refused request answers 429 with Retry-After set to the same number of seconds. The limit is enforced per IP address and is deliberately generous; if you need more for something interesting, write to hello@restrike.co rather than sharding across addresses.

Errors

Every failure returns JSON in one shape: a rejected parameter, an unknown path, a fault on our side alike. There are no HTML error pages anywhere on the API.

{
  "error": "not_found",
  "message": "Type not found.",
  "hint": "Check the slugs against GET /issuers and GET /types.",
  "docs": "https://api.restrike.co/docs"
}

error is the stable, machine-readable part and is safe to branch on: invalid_request, unauthorized, forbidden, not_found, rate_limited, unavailable, internal_error. message is prose and may be reworded. hint says what to change about the request.

Using this API from an agent

The OpenAPI document is written to be turned into tools without a human naming each one:

• Every operation has a unique operationId (getType, listTypes, getGoldSpot) usable directly as a function name.
• Every operation has a description saying what it returns and when to reach for it.
• Every parameter and every response is typed, including the error bodies.
• servers, contact, license and externalDocs are all populated, so a generator has somewhere to point.

Point your tool generator at https://api.restrike.co/openapi.json and it should need no hand editing.

Markdown instead of HTML

Every public page on restrike.co is also served as markdown, following the acceptmarkdown.com convention. Ask for it:

curl -s -H 'Accept: text/markdown' https://restrike.co/coins/south-africa/krugerrand/1-ounce

You get Content-Type: text/markdown; charset=utf-8 and Vary: Accept. A client that asks for a media type we cannot produce gets a 406 naming what is available, rather than an HTML page it then has to strip. This is far cheaper than parsing the rendered site, and it is the intended route for anything reading the reference pages.

Terms

Free to read and free to build on, within the rate limits above. Two conditions: do not present the catalogue as your own (attribute it, with a link to the type page you took the data from) and do not hotlink the images; they are served from our CDN and paid for by us.

The Numista identifiers carried on types are references to Numista's catalogue, not a licence to its data; Numista's own terms apply to anything you fetch from Numista.

Questions: hello@restrike.co.