# Manifest docs

> Every One Piece Card Game card and printing, in English and Japanese, with each printing linked across languages, IDs that never change and a free, read-only JSON API.

The OpenAPI spec describes every endpoint in full: https://manifestcards.app/openapi.json

---

# The Manifest API

Source: https://manifestcards.app/docs

Every One Piece Card Game card and printing, in English and Japanese, linked across languages and given IDs that never change. JSON over HTTPS, and free.

```sh
curl "https://api.manifestcards.app/v1/cards/OP01-120?lang=en" \
  -H "X-API-Key: $MANIFEST_KEY"
```

## The basics

- **Base URL.** Every endpoint lives under `https://api.manifestcards.app/v1`.
- **Keys.** Send yours in the `X-API-Key` header. See [Authentication](https://manifestcards.app/docs/authentication).
- **Responses.** JSON, wrapped in `data`. Lists add `meta` and page with a cursor. See [Requests and responses](https://manifestcards.app/docs/requests).
- **Languages.** `lang=en`, `lang=ja`, or `lang=all` (the default) picks which names, text and printings come back.

## What's in the catalog

**Cards** are game objects: cost, power, colors and text. **Printings** are the physical versions of a card, one per language and product, each with its own art, rarity and image. **Sets** are the products they were released in. [Cards and printings](https://manifestcards.app/docs/concepts) explains how they fit together, and how English and Japanese printings are linked.

## Reference

### [Cards](https://manifestcards.app/docs/reference/cards)

Game objects: stats and text, the same in every language.

- `GET /v1/cards`: List cards
- `GET /v1/cards/{id}`: Get a card

### [Printings](https://manifestcards.app/docs/reference/printings)

Each physical version of a card, in one language.

- `GET /v1/printings`: List printings
- `GET /v1/printings/{id}`: Get a printing
- `GET /v1/lookup`: Look up a marketplace id

### [Sets](https://manifestcards.app/docs/reference/sets)

Products: boosters, decks and promos.

- `GET /v1/sets`: List sets
- `GET /v1/sets/{id}`: Get a set

### [Meta](https://manifestcards.app/docs/reference/meta)

Service status.

- `GET /v1/health`: Check health

The whole API is also described by its [OpenAPI spec](https://manifestcards.app/openapi.json), for code generators and other tools.

---

# Authentication

Source: https://manifestcards.app/docs/authentication

Every request needs a key, except the health check. Keys are free.

## Getting a key

[Sign in](https://manifestcards.app/sign-in) with an email code or GitHub, then create a key on your [profile](https://manifestcards.app/profile). The full key is shown once, when you create it. You can hold up to 5 active keys and revoke any of them there; a revoked key stops working right away.

## Sending your key

Put it in the `X-API-Key` header:

```sh
curl "https://api.manifestcards.app/v1/sets?lang=en" \
  -H "X-API-Key: $MANIFEST_KEY"
```

A missing, unknown or revoked key gets `401 unauthorized`. Keep keys on your server: anyone holding one can spend its quota. Manifest stores only a SHA-256 hash of each key, so a lost key can't be recovered, only replaced.

## Rate limits

Each key gets **60 requests a minute** and **10,000 a day**. Every response says where you stand:

- `X-RateLimit-Limit`: requests allowed per minute.
- `X-RateLimit-Remaining`: requests left in whichever window is closer to running out.
- `X-RateLimit-Reset`: seconds until that window resets.

Past the limit, the API answers `429 rate_limited` with a `Retry-After` header, in seconds. Usage is counted per key per day, and each key belongs to the account that created it.

---

# Requests and responses

Source: https://manifestcards.app/docs/requests

The API is read-only: every endpoint is a `GET` that answers with JSON.

## Envelopes

A single record comes back in `data`, and a list comes back as an array in `data` with paging details in `meta`.

```json
{
  "data": { "number": "OP01-120", "category": "character" }
}
```

## Pagination

Lists return up to `limit` records: 1 to 200, 50 by default. When there are more, `meta.next_cursor` holds a cursor. Pass it back as `?cursor=` with the same filters to get the next page. It's `null` on the last page. Cursors are opaque, so don't build or parse them.

```sh
curl "https://api.manifestcards.app/v1/printings?set=OP-01&limit=100" \
  -H "X-API-Key: $MANIFEST_KEY"
```

## Languages

`lang` picks which localizations a card carries and which printings and sets are listed: `en`, `ja`, or `all`, the default. With `lang=en`, a card has only English text, and only printings released in English come back.

## Errors

Errors use HTTP status codes, and the body always has the same shape:

```json
{ "error": { "code": "not_found", "message": "no card OP99-999" } }
```

- `400 bad_request`: a parameter is missing or invalid. The message names it.
- `401 unauthorized`: the key is missing, unknown or revoked.
- `404 not_found`: nothing has that id, number or code.
- `429 rate_limited`: over the limit. Wait for `Retry-After` seconds.
- `500 internal`: our fault. Try again later.

## Caching

Every response carries an `ETag`. Send it back in `If-None-Match` and you get an empty `304 Not Modified` until the data changes. Data responses are also marked `Cache-Control: private, max-age=300`, so reusing one for five minutes is safe.

## Images

Every printing has two image fields. `image_url` is Manifest's own copy: put it straight in an `<img>` tag, no key needed. `official_image_url` is the same image on Bandai's site. Browsers refuse to show Bandai's images on other sites, but servers and bots can still fetch them.

---

# Cards and printings

Source: https://manifestcards.app/docs/concepts

Manifest keeps two kinds of record apart: the card you play with, and the physical versions of it that exist.

## Cards

A card is the game object: its number, category, colors, cost, power, counter and attributes. These are the same in every language. Names, traits and effect text sit under `localizations`, keyed by language.

```sh
curl "https://api.manifestcards.app/v1/cards/OP01-120" \
  -H "X-API-Key: $MANIFEST_KEY"
```

## Printings

A printing is one physical version of a card, in one language, released in one product. OP01-120 Shanks has thirteen: six in English and seven in Japanese, across the original booster, later reprints and promos. Each printing has its own rarity, variant (`base`, `parallel`, `reprint` and so on) and image.

## English and Japanese, linked

The same printing in both languages shares a `group_id`. Base printings link by card number. The rest pair up by product, rarity and position, and every pair is checked by comparing the artwork itself. A printing released in only one language has no group, and `single_language` is `true`.

```sh
curl "https://api.manifestcards.app/v1/printings?card=OP01-120&lang=all" \
  -H "X-API-Key: $MANIFEST_KEY"
```

## IDs

Every record has an ID like `crd_01m64rkxdcn221cab7nycmgytt`: a prefix (`set_`, `crd_`, `prt_` or `pgr_`) and a ULID. IDs never change and are never reused, so they're safe to store. Treat them as opaque: show the readable fields (`number`, `code`, `official_id`) and key your own data by ID.

## Verification and provenance

Every record says how sure Manifest is about it in `verification.status`:

- `verified`: every check agrees.
- `auto_resolved`: decided by a rule or a reviewed correction. `reason` says which.
- `flagged`: ambiguous or contradictory. `reason` says why. Flagged records are still served.

`provenance` lists the official pages a record was built from, when each was fetched, and a hash of exactly what was read.

---

# Build with AI

Source: https://manifestcards.app/docs/build-with-ai

Coding agents write better Manifest code when they know the base URL, the key header and a few rules about paging, limits and IDs. Everything they need fits in one block.

## Context for your agent

Paste this into your agent's chat or system prompt, or keep it in your repo as a rules file.

```md
# Manifest API

Manifest is a free, read-only JSON API for every One Piece Card Game card and printing, in English and Japanese, with each printing linked across languages and given an ID that never changes.

- Base URL: https://api.manifestcards.app/v1
- Auth: send the key in the `X-API-Key` header. Keys are free: sign in at https://manifestcards.app/sign-in and create one on https://manifestcards.app/profile. Read it from an environment variable such as `MANIFEST_KEY`, keep it on the server, and never commit it.
- Docs index: https://manifestcards.app/llms.txt
- Every guide in one file: https://manifestcards.app/llms-full.txt
- Every endpoint, parameter and field: https://manifestcards.app/openapi.json (OpenAPI 3.1)

## Rules

- Every endpoint is a `GET` that answers with JSON. A record comes back in `data`; a list comes back in `data` with `meta`.
- Page lists with `meta.next_cursor`: pass it back as `?cursor=` with the same filters until it is `null`. `limit` is 1 to 200 (default 50). Cursors are opaque: never build or parse them.
- Each key gets 60 requests a minute and 10,000 a day. Read `X-RateLimit-Remaining` and `X-RateLimit-Reset`, request one page at a time, and on `429 rate_limited` wait `Retry-After` seconds before retrying.
- Cache responses. They are safe to reuse for 5 minutes (`Cache-Control: private, max-age=300`), and sending the `ETag` back in `If-None-Match` returns `304 Not Modified` until the data changes.
- IDs (`set_`, `crd_`, `prt_`, `pgr_` plus a ULID) never change and are never reused. Store them and key your data by them, but treat them as opaque.
- A card is the game object (cost, power, colors, text). A printing is one physical version of it in one language and product.
- The English and Japanese versions of a printing share a `group_id` (`null` when `single_language` is `true`). To pair them, list `/v1/printings?card={number}&lang=all` and match on `group_id`. Never pair by card number or suffix.
- `lang` is `en`, `ja` or `all` (the default).
- Show images with `image_url`. Browsers refuse `official_image_url` (Bandai's copy) on other sites.
- There is no price data. Don't look for price fields or make prices up.
- Errors look like `{ "error": { "code": "...", "message": "..." } }`: `400 bad_request`, `401 unauthorized`, `404 not_found`, `429 rate_limited`, `500 internal`.
```

## A rules file for your repo

The same block, served as a file. [AGENTS.md](https://manifestcards.app/agents.md) is read by most coding agents, and [SKILL.md](https://manifestcards.app/skill.md) is a Claude skill that loads it whenever the agent works with the API. Run these from your repo's root:

```sh
# AGENTS.md, for most coding agents (appends if you have one)
curl https://manifestcards.app/agents.md >> AGENTS.md

# A Claude skill
mkdir -p .claude/skills/manifest-api
curl -o .claude/skills/manifest-api/SKILL.md https://manifestcards.app/skill.md
```

Then create a key on your [profile](https://manifestcards.app/profile) and put it in `MANIFEST_KEY`.

## llms.txt or the OpenAPI spec

- **[llms.txt](https://manifestcards.app/llms.txt)** is a short index of every page. Point an agent at it when it needs to find its way around, and let it open only the pages it needs.
- **[llms-full.txt](https://manifestcards.app/llms-full.txt)** is every guide in one markdown file. Give it to an agent that's new to Manifest, so it learns how cards, printings, paging and errors work.
- **[openapi.json](https://manifestcards.app/openapi.json)** describes every endpoint, parameter and field exactly. Use it when the agent writes request code or generates types and clients.

Most projects want both: the context block or llms-full.txt for how the API behaves, and the OpenAPI spec for the exact shapes. Every docs page also has a Copy as Markdown button, for pasting one page into a chat.