Quickstart

Rarity is a read-only REST API for trading card game catalogs. Reads work without a key, so you can start from a terminal.

Make a requestCopy Anchor Link

curl -A 'my-app/1.0 (you@example.com)' \
  'https://api.rarity.dev/v1/cards?game=pokemon&q=name:charizard&limit=1'

The -A flag matters. The API needs a User-Agent that names your application and refuses the defaults of curl and of HTTP libraries, so a bare curl gets a 400 with the code user_agent_not_allowed. Use your own application name and a real contact.

Read the responseCopy Anchor Link

A search always answers with a list:

{
  "object": "list",
  "data": [
    {
      "object": "card",
      "id": "3cc2b08f-a3bf-56fd-b8b0-2c886511cd20",
      "game": "pokemon",
      "lang": "en",
      "name": "Charizard",
      "set": "M24",
      "collector_number": "001/015",
      "image": "https://images.rarity.dev/cards/3cc2b08f-a3bf-56fd-b8b0-2c886511cd20.jpg"
    }
  ],
  "has_more": true,
  "next_cursor": "..."
}

The card is shortened here. has_more is the one signal that more pages exist: send next_cursor back as cursor to read the next one.

Limits without a keyCopy Anchor Link

The anonymous lane allows 30 requests a minute and 1,000 a day. A free key allows 60 requests a minute per key and 2,000 a day per organization. A daily allowance refills continuously and has no midnight reset, so a burst followed by steady use can approach twice the number in 24 hours. Responses from the API report where you stand in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 carries Retry-After, plus upgrade_url in the error when the request had a key. A response served from the CDN cache keeps the headers of whoever fetched it first, so trust them only when CF-Cache-Status is not HIT, STALE or UPDATING.

Send the ETag of a response back as If-None-Match. A 304 is free: it does not count against either limit.

Use a keyCopy Anchor Link

A key identifies your application and raises your limits. Send it as a bearer token:

curl -A 'my-app/1.0 (you@example.com)' \
  -H "Authorization: Bearer $RARITY_API_KEY" \
  'https://api.rarity.dev/v1/cards?game=pokemon&q=name:charizard&limit=1'

Plans and limits are on the pricing page.

Use the TypeScript SDKCopy Anchor Link

The SDK is a typed client generated from the OpenAPI document. It works with no key and with one.

Note: the SDK and the MCP server below are not published yet. This page will give their names and install commands when they are.

import { createRarityClient } from "<sdk-package>"

const rarity = createRarityClient({
  userAgent: "my-app/1.0 (you@example.com)",
  apiKey: process.env.RARITY_API_KEY, // optional
})

const { data, error } = await rarity.GET("/cards", {
  params: { query: { game: "pokemon", q: "name:charizard", limit: 1 } },
})

data holds the response and error the error object: one of the two is set. The client adds no retries or automatic pagination, so each call is one request.

Connect an AI agentCopy Anchor Link

The MCP server gives an agent one read-only tool for each public JSON read in the reference. It has no write tools and adds no logic of its own.

It speaks MCP over stdio. Add it to your client's configuration:

{
  "mcpServers": {
    "rarity": { "command": "<mcp-command>" }
  }
}

With no configuration it reads in the anonymous lane. To use a key, set RARITY_API_KEY in the environment the client starts it with.

From a browserCopy Anchor Link

The API answers cross-origin GET and HEAD requests from any site, so a page can call it directly with no key, and the playground in the reference works the same way.

Warning: a rar_live_ key in a browser app is an exposed key. Anyone who opens the page can read it and spend your limits. Call the API from your server when you need a key.

A page cannot read the response to a POST, and a request that sends a key to one is refused before it leaves the browser. Writes belong on your server.

NextCopy Anchor Link

• Browse the API reference and try each read in the playground.
• Coming from pokemontcg.io? Follow the migration guide.
• Every error links to its page in the error list.