REST API guide

Create an API key

Open Developer, name your integration and choose Create read-only key. Copy the key when it appears and store it as a secret. A key expires after 90 days and can be revoked from the same screen.

Make your first request

Set NUMIAGENT_API_KEY in your environment. Send it in the Authorization header with the Bearer scheme. For an unauthenticated health check, use GET /api/v1/health.

curl -fsS -H "Authorization: Bearer $NUMIAGENT_API_KEY" "https://numiagent.com/api/v1/items?q=Trajan&page=0"

Read the collection

API keys can read collection folders, specimens and counts, import status, private photos and identification candidates, themes and missing slots, saved watchlists, valuations and their history, references, and marketplace search coverage.

OpenAPI marks key-enabled operations with developerKey. Account management, bulk exports and changes to the catalog use the signed-in browser session.

Page through results

GET /api/v1/items accepts q, page, type, collection, and sort. Start at page 0 and use next from each response until it is null. Use the item id to request a specimen or its valuation. Photo endpoints stream the original stored image or return identification status as JSON, depending on the path.

Handle errors and limits

A 401 means the key is missing, invalid, expired, or revoked. A 403 means the operation requires a browser session. A 404 means the resource is unavailable to this account. API keys share 120 requests per minute per account. Wait before retrying a 429 response. Marketplace queries also count toward the account’s marketplace quota.