🔌 API Reference

REST API v1 · JSON · Sanctum bearer tokens

Base URL

https://collectorita.com/api/v1

Every response is JSON. List endpoints are paginated Laravel-style (data, links, meta). Errors use standard HTTP status codes with { "message": "…", "errors": { … } }.

Authentication

Create a personal access token under Settings → API tokens, or exchange credentials:

curl -X POST https://collectorita.com/api/v1/auth/token \
  -H 'Accept: application/json' \
  -d identifier=YOUR_USERNAME -d password=YOUR_PASSWORD -d device_name=cli

Send the token on every authenticated request:

Authorization: Bearer <token>

Abilities. Tokens are scoped:

  • Credential exchange (POST /auth/token) issues the full standard set: collection:read, collection:write, catalog:read, binder:read, binder:write, trade:read, trade:write, wishlist:read, wishlist:write.
  • Settings → API tokens issues a narrower token: collection:read, collection:write, catalog:read. Use credential exchange if you need binders, trades or wishlists.
  • Admin accounts receive *, which satisfies every ability.

A request whose token lacks the required ability returns 403.

Rate limits

  • Public catalog — per IP.
  • Token exchange — tight per-IP limit (brute-force protection).
  • Authenticated — per user.

All three return 429 with a Retry-After header when exceeded.

Authentication

MethodEndpointAuthNotes
POST /auth/token none Exchange credentials for a bearer token. Body: identifier (username or email), password, optional device_name. Returns { token, token_type, abilities, user }.
GET /me any token The authenticated user and the current token's abilities.
POST /auth/revoke any token Revoke the token used for this request.

Catalog (public)

MethodEndpointAuthNotes
GET /games none All active games.
GET /sets none Sets. Query: game_id, language, page.
GET /search none Card search. Query: q (required), game_id, set_id, rarity, artist, page, per_page (max 100).
GET /cards/{card} none One card with its set, rarity, artist and printings.
GET /graders none Grading companies and their valid grade labels — use to build a grading form.
GET /sets/{set}/{mode}/completion none mode = MAIN | MASTER | GRANDMASTER. Required / owned / missing counts, % and value split. Owned counts require a token.
GET /sets/{set}/{mode}/checklist none Every required printing for the set + mode, each flagged owned / missing.

Collection

MethodEndpointAuthNotes
GET /collection collection:read Your entries in the active (or portfolio_id) collection. Query: set_id, kind, per_page (max 100), page.
GET /collection/stats collection:read Totals: unique cards, copies, market value, cost basis, unrealised gain.
GET /collection/{entry} collection:read A single entry.
POST /collection collection:write Add an entry. See the entry body below.
PATCH /collection/{entry} collection:write Update an entry (same fields as create).
DELETE /collection/{entry} collection:write Remove an entry. 204 on success.

Portfolios (collections)

MethodEndpointAuthNotes
GET /portfolios collection:read Your named collections.
POST /portfolios collection:write Create one. Body: name.
PATCH /portfolios/{portfolio} collection:write Rename.
POST /portfolios/{portfolio}/make-default collection:write Make this the default collection.
DELETE /portfolios/{portfolio} collection:write Delete (entries move to the default).

Binders

MethodEndpointAuthNotes
GET /binders binder:read Your binders.
GET /binders/{binder} binder:read One binder with its slots.
POST /binders binder:write Create. Body: name, optional layout, visibility.
PATCH /binders/{binder} binder:write Update name / layout / visibility.
POST /binders/{binder}/slot binder:write Set a slot. Body: position, card_id, optional card_printing_id.
DELETE /binders/{binder}/slot/{position} binder:write Clear a slot.
POST /binders/{binder}/add-card binder:write Append a card. Body: card_id, optional card_printing_id, position.
POST /binders/{binder}/reorder binder:write Body: order (array of slot positions).
DELETE /binders/{binder} binder:write Delete the binder.

Wishlists

MethodEndpointAuthNotes
GET /wishlists wishlist:read Your wishlists.
GET /wishlists/{wishlist} wishlist:read One wishlist with items.
POST /wishlists wishlist:write Create. Body: name, optional visibility.
POST /wishlists/{wishlist}/items wishlist:write Add an item. Body: card_id, optional card_printing_id.
POST /wishlists/{wishlist}/items/{item}/acquire wishlist:write Mark an item acquired (moves it toward your collection flow).
DELETE /wishlists/{wishlist}/items/{item} wishlist:write Remove an item.
DELETE /wishlists/{wishlist} wishlist:write Delete the wishlist.

Trades

MethodEndpointAuthNotes
GET /trades trade:read Your trades.
GET /trades/{trade} trade:read One trade with both sides.
POST /trades trade:write Start a trade.
POST /trades/{trade}/items trade:write Add an item to one side. Body: side (give/get), card_id, quantity.
PATCH /trades/{trade}/items/{item} trade:write Update a trade item.
DELETE /trades/{trade}/items/{item} trade:write Remove a trade item.
PATCH /trades/{trade} trade:write Set the trade partner.
POST /trades/{trade}/execute trade:write Execute — moves cards between collections.
POST /trades/{trade}/decline trade:write Decline the trade.
DELETE /trades/{trade} trade:write Delete a draft trade.

Collection entry body

Fields accepted by POST /collection and PATCH /collection/{entry}:

{
  "card_id":          123,                // or card_printing_id
  "card_printing_id": 456,
  "portfolio_id":     7,                  // omit → default collection
  "kind":             "RAW",              // RAW | GRADED | SEALED | PROMO | ERROR | MISC
  "quantity":         1,
  "language":         "EN",
  "condition":        "NEAR_MINT",        // MINT | NEAR_MINT | EXCELLENT | GOOD | LIGHT_PLAYED | PLAYED | POOR
  "purchase_price":   12.50,              // optional
  "purchase_date":    "2026-01-05",       // optional
  "current_value":    30.00,              // optional — omit to track the catalog price
  "grader_slug":      "psa",              // see GET /graders
  "grade":            "9 Mint",           // must match the grader's scale (free text for "custom")
  "cert_number":      "12345678",
  "notes":            "…",
  "visibility":       "PUBLIC"            // PRIVATE | UNLISTED | PUBLIC
}

Nothing except a card reference is required — value, grade and condition are all optional.

Grading companies

Live from GET /graders:

PSA psaCGC cgcBeckett (BGS) bgsTAG tagSGC sgcACE aceCustom custom

Collectorita uses only a sign-in cookie needed to run the site — no analytics or advertising trackers. Some outbound store links are affiliate links. Cookie details.

Privacy policy