Flint API and MCP

Public JSON lives on https://api.flint.cards. Accounts, docs, and billing live on flint.cards. This is not a Beckett grade. Unofficial pre-grade is not on this API.

Auth

Create an account at /auth/sign-up. Sign in at /auth/sign-in. Browser session cookies work on the account pages.

JSON callers send Authorization: Bearer <token>. The token is a Flint API key (flt_ prefix) or an access token. Unauthenticated calls return 401.

MCP clients can complete OAuth 2.1 authorization code with PKCE at /oauth/authorize and /oauth/token. Discovery is /.well-known/oauth-authorization-server. A Flint API key is also accepted as Bearer on POST /mcp.

{
  "accountId": "44444444-4444-4444-8444-444444444444",
  "userId": "signed-in-user-id"
}

GET /api/v1/me returns that shape. accountId is the Flint owner id. userId is the signed-in user id.

API keys

Manage keys at /account/api-keys while signed in. POST /api/v1/me/api-keys returns key once. Later lists do not show the secret. Key create and revoke require a session or access token, not another API key. Keys inherit the owner plan and scan quota. Revoked keys fail immediately.

Identify a card

POST /api/v1/scans and the MCP tool scan_card take a well-lit, centered front photo. Flint's identification service identifies the catalog card. Pass copy_id to attach to an owned copy. Omit it to mint a new copy UUID. Scanning the same card twice without copy_id creates two copies. The image is not stored.

{
  "front_image_base64": "<base64 front photo>",
  "copy_id": null
}

A successful identified response looks like this. copy_id is the owned copy. catalog_card_id is catalog identity. They are different fields. This is not a Beckett grade.

{
  "scan_id": "11111111-1111-4111-8111-111111111111",
  "copy_id": "22222222-2222-4222-8222-222222222222",
  "catalog_card_id": "33333333-3333-4333-8333-333333333333",
  "id_vendor": "identification_service",
  "vendors_tried": [
    "identification_service"
  ],
  "status": "identified",
  "counts_toward_quota": true,
  "confidence": 0.92,
  "catalog": {
    "vendorCatalogId": "set|1|name",
    "set": "Example Set",
    "number": "1",
    "player": "Example",
    "variant": null,
    "parallel": null
  },
  "variant_resolution": {
    "state": "resolved",
    "identity": {
      "vendorCatalogId": "set|1|name",
      "set": "Example Set",
      "number": "1",
      "player": "Example",
      "variant": null,
      "parallel": null
    }
  },
  "vendor_price_stats": {
    "available": false,
    "label": "vendor price stats"
  }
}

vendor price stats is its own block. It is not sold comps and not live listings. When stats are missing, available is false. Flint does not guess a number.

Unresolved variants return variant_resolution.state = "unresolved" with candidates. Over-quota calls return 429 quota_exceeded and do not call the identification service.

Collection

Owner-scoped reads. Another user's copy or scan id is 404. There is no card-level qty. Two physical copies are two rows.

{
  "copies": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "catalog_card_id": "33333333-3333-4333-8333-333333333333",
      "catalog": {
        "id_vendor": "identification_service",
        "vendor_catalog_id": "set|1|name",
        "set": "Example Set",
        "number": "1",
        "player": "Example",
        "variant": null,
        "parallel": null
      },
      "created_at": "2026-10-04T00:00:00.000Z"
    }
  ],
  "next_cursor": null
}

MCP

POST https://api.flint.cards/mcp. JSON-RPC methods include initialize, tools/list, and tools/call.

scan_card

Identify one catalog card from a well-lit, centered front photo. Identification uses Flint's identification service. Stores one owned copy UUID. Catalog identity is not the copy. Returns vendor price stats as their own block, never mixed with sold comps or live listings. This is not a Beckett grade. Unofficial pre-grade is not available here. Failed and unidentified scans do not count against the monthly quota.

list_copies

List the signed-in user's owned physical copies, newest first. Each item is one Flint copy UUID, not a catalog quantity. Catalog identity is a separate field. This is copy-level inventory, not a Beckett grade.

get_copy

Get one owned copy by Flint copy UUID. Another user's id is not found. Catalog identity is not the copy. This is not a Beckett grade.

Quota

Failed and unidentified scans do not count against the monthly quota. Limits come from plan config. The UTC month is the period. GET /api/v1/me/usage returns used and remaining.

{
  "period_start": "2026-10-01",
  "plan": "free",
  "limit": 10,
  "used": 1,
  "remaining": 9,
  "by_surface": {
    "http": 1,
    "mcp": 0
  },
  "by_api_key": []
}

Paid Collector and Dealer checkout is on /account/billing.

HTTP reference

Handlers live under /api/v1. /v1/* rewrites to the same routes.