API overview

The AI Card Vault API lets you read and write your inventory programmatically. It's the same surface our web UI uses, exposed under stable JSON contracts. Useful for syncing with your own systems, building custom dashboards, or automating workflows the vault doesn't have built-in yet.

Base URL

https://aicardvault.io/api

Authentication

API access uses bearer tokens scoped to your account. Generate one at /settings/api (interface coming in Wave 5). Tokens are long-lived but revocable — rotate them from the same screen if you suspect a leak.

Include the token in the Authorization header on every request:

Authorization: Bearer cv_live_abc123...

The token prefix tells you the environment: cv_live_ for production, cv_test_ for the (forthcoming) sandbox.

Rate limits

Defaults per token:

• 60 requests / minute for read endpoints (GET)
• 20 requests / minute for write endpoints (POST, PATCH, DELETE)
• 5 requests / minute for AI endpoints (identify, price-lookup) — these cost real money and are heavier

Limits return 429 Too Many Requests with a Retry-After header. We send the same headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on every response so you can pace yourself.

What's available

The Wave 5 launch surface covers the read paths and a small set of writes:

• GET /cards — list cards with filters (status, batch, location, set, etc.)
• GET /cards/:id — fetch a single card
• PATCH /cards/:id — update a card (identification, pricing, location)
• GET /batches — list batches
• GET /batches/:id/cards — list cards in a batch
• POST /identify — run identification on a card or photo URL
• GET /listings — list eBay listings
• POST /listings/:cardId/publish — publish a card to eBay

Full endpoint reference will live at /help/api/reference once Wave 5 closes out.

Errors

Errors come back as JSON with a stable shape:

{
  "error": {
    "code": "card_not_found",
    "message": "No card with ID 12345 in your account.",
    "status": 404
  }
}

Error codes are stable strings you can dispatch on. The human-readable message is for logs and end users.

Versioning

The current API is v1, implied by the lack of version prefix. When we add v2 it'll live at /api/v2/* and /api/* will continue serving v1 for at least 12 months after v2 ships.