Skip to main content

PoketDex Developer API

Clear, production-ready docs for building on top of PoketDex.

Use PoketDex APIs to authenticate collectors, sync collection data, power marketplace experiences, search the card catalog, manage social profiles, and plug into local event discovery.

Base URL

https://api.pocketdex.io

Auth

Bearer token

Format

JSON request / response payloads

Version

Public /api routes

Read the docsCreate account

Overview

API fundamentals

The PoketDex API is organized around predictable REST endpoints. Requests and responses use JSON, and authenticated routes expect a Bearer token in the Authorization header. The docs below cover the core public resources most partner apps and internal tools need first.

REST-style resource paths
JSON payloads for requests and responses
Consistent auth, rate-limit, and error handling patterns

Authentication

Bearer token access

Authenticate by sending a Bearer token with every protected request:

Authorization: Bearer <token>

To get a token, call POST /api/auth/login with a valid email and password. The response returns a token that can be reused until expiry or logout.

Request
POST /api/auth/login
Content-Type: application/json

{
  "email": "misty@pocketdex.io",
  "password": "super-secure-password"
}
Authenticated header
GET /api/collection
Authorization: Bearer <token>

Endpoints

Reference by resource

Each endpoint includes a purpose statement, sample JSON payloads, and a curl example for quick testing.

Auth

Auth endpoints

Create accounts, exchange credentials for tokens, and revoke active sessions.

POST/api/auth/login

Authenticate a user and return an access token for Bearer-authenticated requests.

JSON request
{
  "email": "misty@pocketdex.io",
  "password": "super-secure-password"
}
JSON response
{
  "token": "pk_live_eyJhbGciOi...",
  "expiresIn": 3600,
  "user": {
    "id": "usr_1024",
    "username": "misty",
    "email": "misty@pocketdex.io"
  }
}
curl example
curl -X POST https://api.pocketdex.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "misty@pocketdex.io",
    "password": "super-secure-password"
  }'
POST/api/auth/register

Create a new PoketDex account for a collector or dealer.

JSON request
{
  "username": "brock",
  "email": "brock@pocketdex.io",
  "password": "another-secure-password",
  "plan": "free"
}
JSON response
{
  "user": {
    "id": "usr_2048",
    "username": "brock",
    "email": "brock@pocketdex.io",
    "plan": "free"
  },
  "created": true
}
curl example
curl -X POST https://api.pocketdex.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "brock",
    "email": "brock@pocketdex.io",
    "password": "another-secure-password",
    "plan": "free"
  }'
POST/api/auth/logout

Invalidate the current access token and close the active session.

No request body required.
JSON response
{
  "success": true,
  "message": "Logged out successfully"
}
curl example
curl -X POST https://api.pocketdex.io/api/auth/logout \
  -H "Authorization: Bearer <token>"

Collection

Collection endpoints

Manage a user’s portfolio inventory, ownership metadata, and exports.

GET/api/collection

List cards in the authenticated user’s collection with pricing and quantity data.

No request body required.
JSON response
{
  "items": [
    {
      "id": "col_1",
      "cardId": "base1-4",
      "name": "Charizard",
      "quantity": 2,
      "condition": "NM",
      "marketValue": 875.5
    }
  ],
  "total": 1
}
curl example
curl https://api.pocketdex.io/api/collection \
  -H "Authorization: Bearer <token>"
POST/api/collection

Add a new card to a user’s collection.

JSON request
{
  "cardId": "base1-4",
  "quantity": 1,
  "condition": "NM",
  "purchasePrice": 820,
  "acquiredAt": "2026-04-02"
}
JSON response
{
  "item": {
    "id": "col_99",
    "cardId": "base1-4",
    "quantity": 1,
    "condition": "NM",
    "purchasePrice": 820
  }
}
curl example
curl -X POST https://api.pocketdex.io/api/collection \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "base1-4",
    "quantity": 1,
    "condition": "NM",
    "purchasePrice": 820,
    "acquiredAt": "2026-04-02"
  }'
PATCH/api/collection/:id

Update quantity, condition, notes, or pricing metadata for an owned card.

JSON request
{
  "quantity": 3,
  "condition": "LP",
  "notes": "Binder copy plus two trade extras"
}
JSON response
{
  "item": {
    "id": "col_99",
    "quantity": 3,
    "condition": "LP",
    "notes": "Binder copy plus two trade extras"
  }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/collection/col_99 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "condition": "LP",
    "notes": "Binder copy plus two trade extras"
  }'
DELETE/api/collection/:id

Remove a card entry from the authenticated user’s collection.

No request body required.
JSON response
{
  "success": true,
  "deletedId": "col_99"
}
curl example
curl -X DELETE https://api.pocketdex.io/api/collection/col_99 \
  -H "Authorization: Bearer <token>"
GET/api/collection/export

Export collection data as a CSV-ready payload for accounting or backup workflows.

No request body required.
JSON response
{
  "format": "csv",
  "downloadUrl": "https://cdn.pocketdex.io/exports/collection-2026-04-04.csv",
  "expiresAt": "2026-04-04T17:00:00Z"
}
curl example
curl https://api.pocketdex.io/api/collection/export \
  -H "Authorization: Bearer <token>"

Marketplace

Marketplace endpoints

Browse listings, publish inventory, and negotiate offers with other collectors.

GET/api/marketplace/listings

Return active marketplace listings with asking prices and seller metadata.

No request body required.
JSON response
{
  "listings": [
    {
      "id": "lst_77",
      "title": "Charizard ex PSA 10",
      "price": 1399,
      "currency": "USD",
      "seller": {
        "id": "usr_88",
        "username": "cardvault"
      }
    }
  ]
}
curl example
curl https://api.pocketdex.io/api/marketplace/listings \
  -H "Authorization: Bearer <token>"
GET/api/marketplace/listings/:id

Fetch full details for a single listing, including condition and offer status.

No request body required.
JSON response
{
  "listing": {
    "id": "lst_77",
    "title": "Charizard ex PSA 10",
    "description": "Fresh slab, no scratches.",
    "price": 1399,
    "status": "active"
  }
}
curl example
curl https://api.pocketdex.io/api/marketplace/listings/lst_77 \
  -H "Authorization: Bearer <token>"
POST/api/marketplace/listings

Create a new marketplace listing from collection inventory or a direct card record.

JSON request
{
  "cardId": "sv4pt5-234",
  "title": "Charizard ex PSA 10",
  "price": 1399,
  "condition": "GRADED",
  "gradingCompany": "PSA",
  "grade": 10
}
JSON response
{
  "listing": {
    "id": "lst_91",
    "status": "active",
    "price": 1399,
    "title": "Charizard ex PSA 10"
  }
}
curl example
curl -X POST https://api.pocketdex.io/api/marketplace/listings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "sv4pt5-234",
    "title": "Charizard ex PSA 10",
    "price": 1399,
    "condition": "GRADED",
    "gradingCompany": "PSA",
    "grade": 10
  }'
POST/api/marketplace/offers

Submit an offer against an active listing.

JSON request
{
  "listingId": "lst_91",
  "amount": 1325,
  "message": "Ready to pay today if still available."
}
JSON response
{
  "offer": {
    "id": "off_12",
    "listingId": "lst_91",
    "amount": 1325,
    "status": "pending"
  }
}
curl example
curl -X POST https://api.pocketdex.io/api/marketplace/offers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "listingId": "lst_91",
    "amount": 1325,
    "message": "Ready to pay today if still available."
  }'

Cards

Cards endpoints

Search the master card catalog, retrieve card details, and inspect price movement.

GET/api/cards/search?q=charizard

Search the PoketDex card database by name, set, number, or text query.

No request body required.
JSON response
{
  "results": [
    {
      "id": "base1-4",
      "name": "Charizard",
      "set": "Base Set",
      "number": "4/102"
    }
  ]
}
curl example
curl "https://api.pocketdex.io/api/cards/search?q=charizard" \
  -H "Authorization: Bearer <token>"
GET/api/cards/:id

Fetch detailed metadata for a single card, including artwork, rarity, and market stats.

No request body required.
JSON response
{
  "card": {
    "id": "base1-4",
    "name": "Charizard",
    "rarity": "Holo Rare",
    "artist": "Mitsuhiro Arita",
    "marketValue": 875.5
  }
}
curl example
curl https://api.pocketdex.io/api/cards/base1-4 \
  -H "Authorization: Bearer <token>"
GET/api/cards/:id/price-history

Return historical pricing points for charts, alerts, and valuation analysis.

No request body required.
JSON response
{
  "history": [
    { "date": "2026-03-28", "price": 820 },
    { "date": "2026-04-01", "price": 842.5 },
    { "date": "2026-04-04", "price": 875.5 }
  ]
}
curl example
curl https://api.pocketdex.io/api/cards/base1-4/price-history \
  -H "Authorization: Bearer <token>"

Users

Users endpoints

Read and update profile data and manage social follow relationships.

GET/api/users/me

Return the authenticated user’s public and private profile fields.

No request body required.
JSON response
{
  "user": {
    "id": "usr_1024",
    "username": "misty",
    "displayName": "Misty",
    "bio": "Vintage holo collector",
    "followers": 241
  }
}
curl example
curl https://api.pocketdex.io/api/users/me \
  -H "Authorization: Bearer <token>"
PATCH/api/users/me

Update profile details such as display name, bio, avatar, and location.

JSON request
{
  "displayName": "Misty",
  "bio": "Vintage holo collector",
  "location": "Toronto, ON"
}
JSON response
{
  "user": {
    "id": "usr_1024",
    "displayName": "Misty",
    "bio": "Vintage holo collector",
    "location": "Toronto, ON"
  }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/users/me \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Misty",
    "bio": "Vintage holo collector",
    "location": "Toronto, ON"
  }'
POST/api/users/:id/follow

Follow or unfollow another PoketDex user depending on current relationship state.

JSON request
{
  "action": "follow"
}
JSON response
{
  "targetUserId": "usr_88",
  "following": true,
  "followers": 242
}
curl example
curl -X POST https://api.pocketdex.io/api/users/usr_88/follow \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "follow"
  }'

Events

Events endpoints

Power local show discovery, event detail pages, and RSVP flows.

GET/api/events

List upcoming PoketDex events with city, schedule, and attendance summaries.

No request body required.
JSON response
{
  "events": [
    {
      "id": "evt_300",
      "title": "Toronto Spring Card Show",
      "city": "Toronto",
      "startsAt": "2026-04-18T10:00:00Z",
      "attendeeCount": 418
    }
  ]
}
curl example
curl https://api.pocketdex.io/api/events \
  -H "Authorization: Bearer <token>"
GET/api/events/:id

Get complete details for one event, including venue and organizer info.

No request body required.
JSON response
{
  "event": {
    "id": "evt_300",
    "title": "Toronto Spring Card Show",
    "venue": "Metro Convention Hall",
    "address": "255 Front St W",
    "description": "Regional trading card show with dealers and trade tables."
  }
}
curl example
curl https://api.pocketdex.io/api/events/evt_300 \
  -H "Authorization: Bearer <token>"
POST/api/events/:id/rsvp

Create or update the authenticated user’s RSVP for an event.

JSON request
{
  "status": "going",
  "guests": 1
}
JSON response
{
  "rsvp": {
    "eventId": "evt_300",
    "status": "going",
    "guests": 1
  }
}
curl example
curl -X POST https://api.pocketdex.io/api/events/evt_300/rsvp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "going",
    "guests": 1
  }'

Search

Search endpoints

Global search across cards, users, events, listings, and sets from a single endpoint.

GET/api/search?q=&types=&limit=

Search across cards, users, events, marketplace listings, and card sets simultaneously. Uses fuzzy matching to surface results even with typos.

No request body required.
JSON response
{
  "ok": true,
  "data": {
    "cards": [{ "id": "base1-4", "name": "Charizard", "setId": "base1", "setName": "Base Set", "rarity": "Holo Rare", "imageUrl": "https://..." }],
    "users": [{ "id": "usr_1024", "username": "misty", "displayName": "Misty", "avatarUrl": "https://..." }],
    "events": [{ "id": "evt_300", "title": "Toronto Spring Card Show", "location": "Toronto, ON", "startsAt": "2026-04-18T10:00:00Z" }],
    "listings": [{ "id": "lst_77", "title": "Charizard ex PSA 10", "cardName": "Charizard", "setName": "Scarlet & Violet", "price": 1399, "sellerName": "CardVault" }],
    "sets": [{ "id": "sv2", "name": "Paldea Evolved", "series": "Scarlet & Violet", "imageUrl": "https://...", "totalCards": 300 }],
    "total": 7
  }
}
curl example
curl "https://api.pocketdex.io/api/search?q=charizard&types=cards,users&limit=5 \
  -H "Authorization: Bearer <token>"

Social Feed

Social Feed endpoints

Activity feeds showing what collectors in your network are adding, selling, and achieving.

GET/api/feed?type=&cursor=&limit=

Return a paginated activity feed filtered to following users or global public activity.

No request body required.
JSON response
{
  "ok": true,
  "items": [
    {
      "id": "card_added:col_99",
      "type": "card_added",
      "userId": "usr_88",
      "username": "CardVault",
      "cardName": "Charizard",
      "cardImage": "https://...",
      "timestamp": "2026-04-04T14:22:00Z",
      "link": "/card/base1-4"
    }
  ],
  "nextCursor": "2026-04-04T11:59:00Z"
}
curl example
curl "https://api.pocketdex.io/api/feed?type=following&limit=20 \
  -H "Authorization: Bearer <token>"
GET/api/feed/trending

Return the top 20 posts from the last 48 hours sorted by engagement (likes + comments).

No request body required.
JSON response
{
  "ok": true,
  "data": [
    {
      "id": "post_55",
      "authorId": "usr_88",
      "authorName": "CardVault",
      "body": "Finally pulled a PSA 10 Charizard from an ETB!",
      "category": "pickups",
      "cardName": "Charizard",
      "cardImageUrl": "https://...",
      "cardPrice": 875,
      "likeCount": 47,
      "commentCount": 12,
      "createdAt": "2026-04-04T10:00:00Z"
    }
  ]
}
curl example
curl "https://api.pocketdex.io/api/feed/trending \
  -H "Authorization: Bearer <token>"

Posts

Posts endpoints

Community posts with likes and threaded comments.

GET/api/posts?cursor=&category=&limit=

List all public community posts, optionally filtered by category.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "id": "post_55", "authorId": "usr_88", "authorName": "CardVault", "body": "Finally pulled a PSA 10 Charizard!", "category": "pickups", "likeCount": 47, "commentCount": 12, "createdAt": "2026-04-04T10:00:00Z" }],
  "nextCursor": "2026-04-04T09:00:00Z"
}
curl example
curl "https://api.pocketdex.io/api/posts?category=deals&limit=20 \
  -H "Authorization: Bearer <token>"
POST/api/posts

Create a new community post with optional card share attachment.

JSON request
{
  "body": "Just picked up this beauty at the card show.",
  "category": "pickups",
  "cardName": "Pikachu"
}
JSON response
{
  "ok": true,
  "id": "post_99",
  "authorId": "usr_1024",
  "authorName": "Misty",
  "body": "Just picked up this beauty at the card show.",
  "category": "pickups",
  "likeCount": 0,
  "commentCount": 0,
  "createdAt": "2026-04-04T15:00:00Z"
}
curl example
curl -X POST https://api.pocketdex.io/api/posts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"body": "Just picked up this beauty at the card show.", "category": "pickups", "cardName": "Pikachu"}'
POST/api/posts/:id/like

Like a post. Idempotent.

No request body required.
JSON response
{
  "ok": true,
  "liked": true,
  "likeCount": 48
}
curl example
curl -X POST https://api.pocketdex.io/api/posts/post_55/like \
  -H "Authorization: Bearer <token>"
DELETE/api/posts/:id/like

Remove a like from a post.

No request body required.
JSON response
{
  "ok": true,
  "liked": false,
  "likeCount": 47
}
curl example
curl -X DELETE https://api.pocketdex.io/api/posts/post_55/like \
  -H "Authorization: Bearer <token>"
POST/api/posts/:id/comments

Add a comment to a post.

JSON request
{
  "body": "Congrats! What set was it from?"
}
JSON response
{
  "ok": true,
  "data": { "id": "comment_22", "postId": "post_55", "authorId": "usr_2048", "authorName": "Brock", "body": "Congrats! What set was it from?", "createdAt": "2026-04-04T11:00:00Z" }
}
curl example
curl -X POST https://api.pocketdex.io/api/posts/post_55/comments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"body": "Congrats! What set was it from?"}'
DELETE/api/posts/:id

Delete a post. Only the post author can delete their own posts.

No request body required.
JSON response
{
  "ok": true
}
curl example
curl -X DELETE https://api.pocketdex.io/api/posts/post_99 \
  -H "Authorization: Bearer <token>"

Sets

Sets endpoints

Browse the card set catalog and track personal set completion progress.

GET/api/sets

List all card sets in the PoketDex catalog, sorted by release date descending.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "id": "sv2", "name": "Paldea Evolved", "series": "Scarlet & Violet", "totalCards": 300, "releaseDate": "2023-06-01", "imageUrl": "https://...", "symbolUrl": "https://..." }]
}
curl example
curl "https://api.pocketdex.io/api/sets \
  -H "Authorization: Bearer <token>"
GET/api/sets/my-progress

Return all sets the user owns at least one card from, with completion percentages.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "setId": "sv2", "setName": "Paldea Evolved", "series": "Scarlet & Violet", "ownedCount": 120, "totalCards": 300, "completionPct": 40, "imageUrl": "https://..." }]
}
curl example
curl "https://api.pocketdex.io/api/sets/my-progress \
  -H "Authorization: Bearer <token>"
GET/api/sets/:id/progress

Return detailed completion breakdown for a specific set, including missing card list.

No request body required.
JSON response
{
  "ok": true,
  "data": { "setId": "sv2", "setName": "Paldea Evolved", "totalCards": 300, "ownedCount": 120, "completionPct": 40, "missingCards": [{ "cardId": "sv2-1", "name": "Miraidon", "number": "1", "rarity": "Ultra Rare", "averagePrice": 12.5 }] }
}
curl example
curl "https://api.pocketdex.io/api/sets/sv2/progress \
  -H "Authorization: Bearer <token>"

Trades

Trades endpoints

Propose, manage, accept, decline, and counter trade offers between collectors.

GET/api/trades?status=&q=&from=&to=

List all trades involving the authenticated user, optionally filtered by status or partner.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "id": "trade_55", "proposerId": "usr_1024", "receiverId": "usr_88", "status": "pending", "offeredCards": [{ "id": "col_1", "name": "Pikachu", "setName": "SwSh4", "estimatedValue": 45 }], "requestedCards": [{ "id": "col_9", "name": "Charizard", "setName": "base1", "estimatedValue": 875 }], "createdAt": "2026-04-04T10:00:00Z" }]
}
curl example
curl "https://api.pocketdex.io/api/trades?status=pending \
  -H "Authorization: Bearer <token>"
GET/api/trades/:id

Fetch full details for a single trade, including all card sides and message history.

No request body required.
JSON response
{
  "ok": true,
  "data": { "id": "trade_55", "status": "pending", "offeredCards": [], "requestedCards": [], "messages": [{ "id": "msg_1", "senderId": "usr_1024", "body": "Interested in this trade!", "createdAt": "..." }], "proposer": { "id": "usr_1024", "name": "Misty" }, "receiver": { "id": "usr_88", "name": "CardVault" } }
}
curl example
curl "https://api.pocketdex.io/api/trades/trade_55 \
  -H "Authorization: Bearer <token>"
POST/api/trades

Propose a new trade offer to another collector. Maximum 6 cards per side.

JSON request
{
  "receiverId": "usr_88",
  "offeredCardIds": ["col_1", "col_2"],
  "requestedCardIds": ["col_9"],
  "message": "Open to negotiation!"
}
JSON response
{
  "ok": true,
  "data": { "id": "trade_55", "status": "pending", "createdAt": "2026-04-04T10:00:00Z" }
}
curl example
curl -X POST https://api.pocketdex.io/api/trades \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"receiverId": "usr_88", "offeredCardIds": ["col_1", "col_2"], "requestedCardIds": ["col_9"], "message": "Open to negotiation!"}'
PATCH/api/trades/:id/accept

Accept a pending trade. Cards are swapped atomically via a transaction.

No request body required.
JSON response
{
  "ok": true,
  "data": { "id": "trade_55", "status": "completed", "acceptedAt": "2026-04-04T12:00:00Z", "completedAt": "2026-04-04T12:00:00Z" }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/trades/trade_55/accept \
  -H "Authorization: Bearer <token>"
PATCH/api/trades/:id/decline

Decline a pending trade offer.

No request body required.
JSON response
{
  "ok": true,
  "data": { "id": "trade_55", "status": "declined" }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/trades/trade_55/decline \
  -H "Authorization: Bearer <token>"
PATCH/api/trades/:id/cancel

Cancel a pending trade. Only the proposer can cancel.

No request body required.
JSON response
{
  "ok": true,
  "data": { "id": "trade_55", "status": "cancelled" }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/trades/trade_55/cancel \
  -H "Authorization: Bearer <token>"
PATCH/api/trades/:id/counter

Counter a pending trade with a revised set of offered and requested cards. Flips proposer/receiver roles.

JSON request
{
  "offeredCardIds": ["col_7"],
  "requestedCardIds": ["col_9", "col_11"],
  "message": "Revised offer."
}
JSON response
{
  "ok": true,
  "data": { "id": "trade_55", "status": "pending", "proposerId": "usr_88", "receiverId": "usr_1024" }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/trades/trade_55/counter \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"offeredCardIds": ["col_7"], "requestedCardIds": ["col_9", "col_11"], "message": "Revised offer."}'
GET/api/trades/suggestions

Return ranked trade partner suggestions based on overlapping want/have lists.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "partnerId": "usr_88", "score": 3, "cardsTheyHave": [{ "cardId": "sv2-1", "title": "Miraidon" }], "partner": { "id": "usr_88", "name": "CardVault" } }]
}
curl example
curl "https://api.pocketdex.io/api/trades/suggestions \
  -H "Authorization: Bearer <token>"

Grading

Grading endpoints

Track PSA, BGS, CGC, and TAG card grading submissions and monitor their status end-to-end.

GET/api/grading?service=&status=

List all grading submissions for the authenticated user.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "id": "grad_1", "service": "PSA", "tier": "Regular", "status": "grading", "submissionDate": "2026-03-15T00:00:00Z", "estimatedReturnDate": "2026-04-30T00:00:00Z", "declaredValue": 500, "gradingCost": 100, "card": { "cardId": "base1-4", "cardName": "Charizard", "setName": "Base Set" } }]
}
curl example
curl "https://api.pocketdex.io/api/grading \
  -H "Authorization: Bearer <token>"
POST/api/grading

Create a new grading submission for a card the user owns.

JSON request
{
  "cardName": "Charizard",
  "setName": "Base Set",
  "service": "PSA",
  "tier": "Regular",
  "declaredValue": 500,
  "gradingCost": 100
}
JSON response
{
  "ok": true,
  "data": { "id": "grad_5", "service": "PSA", "tier": "Regular", "status": "submitted", "submissionDate": "2026-04-04T10:00:00Z", "estimatedReturnDate": "2026-05-19T00:00:00Z", "declaredValue": 500, "gradingCost": 100, "card": { "cardName": "Charizard", "setName": "Base Set" } }
}
curl example
curl -X POST https://api.pocketdex.io/api/grading \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cardName": "Charizard", "setName": "Base Set", "service": "PSA", "tier": "Regular", "declaredValue": 500, "gradingCost": 100}'
PATCH/api/grading/:id

Update submission status, grade info, or attach the collection item once grading is complete.

JSON request
{
  "status": "completed",
  "receivedGrade": "10",
  "gradedValue": 1500
}
JSON response
{
  "ok": true,
  "data": { "id": "grad_5", "status": "completed", "receivedGrade": "10", "gradedValue": 1500, "roi": 900, "returnedAt": "2026-04-02T14:00:00Z" }
}
curl example
curl -X PATCH https://api.pocketdex.io/api/grading/grad_5 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "receivedGrade": "10", "gradedValue": 1500}'
DELETE/api/grading/:id

Delete a draft grading submission.

No request body required.
JSON response
{
  "ok": true,
  "data": { "deleted": true }
}
curl example
curl -X DELETE https://api.pocketdex.io/api/grading/grad_5 \
  -H "Authorization: Bearer <token>"
GET/api/grading/stats?service=&status=

Return aggregated grading statistics: total submitted, avg grade, avg turnaround, and ROI metrics.

No request body required.
JSON response
{
  "ok": true,
  "data": { "totalSubmitted": 8, "totalReturned": 6, "inProgress": 2, "avgGrade": 8.75, "avgTurnaround": 42.3, "totalInvested": 625, "totalReturn": 4200, "totalRoi": 3575, "avgRoi": 595.83 }
}
curl example
curl "https://api.pocketdex.io/api/grading/stats \
  -H "Authorization: Bearer <token>"

Leaderboards

Leaderboards endpoints

Compete on portfolio value, collection size, trade volume, and set completion leaderboards.

GET/api/leaderboards/portfolio-value

Top 50 collectors ranked by total portfolio value (snapshot-driven).

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "rank": 1, "userId": "usr_88", "username": "CardVault", "avatarUrl": "https://...", "value": 128450.00, "badge": "Collector Elite" }],
  "myRank": 14
}
curl example
curl "https://api.pocketdex.io/api/leaderboards/portfolio-value \
  -H "Authorization: Bearer <token>"
GET/api/leaderboards/collection-size

Top 50 collectors ranked by total number of cards in their collection.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "rank": 1, "userId": "usr_1024", "username": "Misty", "value": 1840, "badge": null }]
}
curl example
curl "https://api.pocketdex.io/api/leaderboards/collection-size \
  -H "Authorization: Bearer <token>"
GET/api/leaderboards/traders?period=30d

Top 50 traders ranked by completed trade count, optionally filtered by time period.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "rank": 1, "userId": "usr_88", "username": "CardVault", "value": 42, "badge": null }]
}
curl example
curl "https://api.pocketdex.io/api/leaderboards/traders?period=30d \
  -H "Authorization: Bearer <token>"
GET/api/leaderboards/graders

Top 50 collectors ranked by number of graded cards in their portfolio.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "rank": 1, "userId": "usr_2048", "username": "Brock", "value": 94, "badge": null }]
}
curl example
curl "https://api.pocketdex.io/api/leaderboards/graders \
  -H "Authorization: Bearer <token>"
GET/api/leaderboards/sets-completed

Top 50 collectors ranked by number of sets completed at 80% or higher.

No request body required.
JSON response
{
  "ok": true,
  "data": [{ "rank": 1, "userId": "usr_88", "username": "CardVault", "value": 12, "badge": null }]
}
curl example
curl "https://api.pocketdex.io/api/leaderboards/sets-completed \
  -H "Authorization: Bearer <token>"

Challenges

Challenges endpoints

Weekly collector challenges that award badges and track progress.

GET/api/challenges/current

Return this week's active challenge, computed progress, and completion status.

No request body required.
JSON response
{
  "ok": true,
  "data": {
    "title": "Card Collector",
    "description": "Add 10 cards to your collection this week",
    "reward": { "badge": "Scan Champion Badge", "key": "scan_champion", "earned": false },
    "progress": 60,
    "completedAt": null
  }
}
curl example
curl "https://api.pocketdex.io/api/challenges/current \
  -H "Authorization: Bearer <token>"

Notifications

Notifications endpoints

Read, manage, and stream real-time notifications for trades, offers, alerts, and social activity.

GET/api/notifications?cursor=&limit=&unread=&type=

List notifications for the authenticated user with optional unread filter and type filter.

No request body required.
JSON response
{
  "ok": true,
  "data": {
    "notifications": [{ "id": "notif_33", "type": "trade_offer", "title": "New trade offer", "body": "CardVault sent you a trade offer.", "isRead": false, "resourceType": "trade", "resourceId": "trade_55", "url": "/trades/trade_55", "createdAt": "2026-04-04T10:00:00Z" }],
    "nextCursor": "2026-04-04T09:00:00Z",
    "unreadCount": 5
  }
}
curl example
curl "https://api.pocketdex.io/api/notifications?limit=20&unread=true \
  -H "Authorization: Bearer <token>"
GET/api/notifications/unread-count

Return the current unread notification count for the authenticated user.

No request body required.
JSON response
{
  "ok": true,
  "data": { "count": 5 }
}
curl example
curl "https://api.pocketdex.io/api/notifications/unread-count \
  -H "Authorization: Bearer <token>"
GET/api/notifications/stream

SSE stream for real-time notification delivery. Sends new_notification, unread_count, and ping events.

No request body required.
JSON response
event: unread_count
data: {"unreadCount": 6, "notificationId": "notif_34"}

event: new_notification
data: {"id": "notif_34", "type": "trade_confirmed", "title": "Trade accepted", ...}

event: ping
data: {"ts": 1743800000000}
curl example
curl "https://api.pocketdex.io/api/notifications/stream \
  -H "Authorization: Bearer <token>" \
  -H "Accept: text/event-stream"
PATCH/api/notifications/:notificationId/read

Mark a single notification as read.

No request body required.
JSON response
{
  "ok": true,
  "data": { "read": true }
}
curl example
curl -X PATCH "https://api.pocketdex.io/api/notifications/notif_33/read \
  -H "Authorization: Bearer <token>"
PATCH/api/notifications/read-all

Mark all notifications as read for the authenticated user.

No request body required.
JSON response
{
  "ok": true,
  "data": { "readAll": true }
}
curl example
curl -X PATCH "https://api.pocketdex.io/api/notifications/read-all \
  -H "Authorization: Bearer <token>"
DELETE/api/notifications/:notificationId

Delete a single notification.

No request body required.
JSON response
{
  "ok": true,
  "data": { "deleted": true }
}
curl example
curl -X DELETE "https://api.pocketdex.io/api/notifications/notif_33 \
  -H "Authorization: Bearer <token>"
DELETE/api/notifications/clear

Delete all read notifications for the authenticated user.

No request body required.
JSON response
{
  "ok": true,
  "data": { "cleared": true }
}
curl example
curl -X DELETE "https://api.pocketdex.io/api/notifications/clear \
  -H "Authorization: Bearer <token>"
POST/api/notifications/push-token

Register an Expo push token for the authenticated user to receive mobile push notifications.

JSON request
{
  "token": "ExponentPushToken[xxxxxx]",
  "platform": "ios"
}
JSON response
{
  "ok": true,
  "data": { "registered": true }
}
curl example
curl -X POST "https://api.pocketdex.io/api/notifications/push-token \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"token": "ExponentPushToken[xxxxxx]", "platform": "ios"}'

Billing

Billing endpoints

Manage PoketDex subscription plans and billing via Stripe — checkout, portal, and webhook handling.

GET/api/billing/status

Return current plan tier, Stripe subscription status, usage stats, and available plan tiers.

No request body required.
JSON response
{
  "ok": true,
  "data": {
    "currentPlan": "pro",
    "stripeConfigured": true,
    "publishableKey": "pk_test_...",
    "customerId": "cus_xxx",
    "priceId": "price_xxx",
    "subscriptionStatus": "active",
    "nextBillingDate": "2026-05-04T00:00:00Z",
    "trialEndDate": null,
    "usage": { "collectionItems": 340, "watchlistItems": 22, "activeListings": 8 },
    "tiers": []
  }
}
curl example
curl "https://api.pocketdex.io/api/billing/status \
  -H "Authorization: Bearer <token>"
POST/api/billing/create-checkout-session

Create a Stripe Checkout session to upgrade to Pro or Dealer.

JSON request
{
  "tier": "pro",
  "platform": "web",
  "successUrl": "https://pocketdex.io/dashboard/billing?success=true",
  "cancelUrl": "https://pocketdex.io/dashboard/billing?canceled=true"
}
JSON response
{
  "ok": true,
  "data": {
    "url": "https://checkout.stripe.com/c/pay/...",
    "sessionId": "cs_test_xxx",
    "customerId": "cus_xxx",
    "priceId": "price_xxx"
  }
}
curl example
curl -X POST "https://api.pocketdex.io/api/billing/create-checkout-session \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tier": "pro", "platform": "web"}'
POST/api/billing/portal

Create a Stripe Customer Portal session for managing payment methods and subscription.

No request body required.
JSON response
{
  "ok": true,
  "data": { "url": "https://billing.stripe.com/c/session/..." }
}
curl example
curl -X POST "https://api.pocketdex.io/api/billing/portal \
  -H "Authorization: Bearer <token>"

Dashboard

Dashboard endpoints

Unified activity feed and portfolio analytics powering the dashboard home experience.

GET/api/dashboard/activity?limit=

Return a merged, timestamp-sorted feed of recent collection adds, listings, sales, trades, price alerts, and scans.

No request body required.
JSON response
{
  "ok": true,
  "data": [
    { "id": "add-col_99", "type": "collection_add", "description": "Added Charizard to collection", "cardName": "Charizard", "cardImage": "https://...", "setName": "Base Set", "timestamp": "2026-04-04T15:00:00Z" },
    { "id": "listing-lst_91", "type": "listing_created", "description": "Listed Pikachu for $45.00", "cardName": "Pikachu", "cardImage": "https://...", "setName": "Scarlet & Violet", "timestamp": "2026-04-04T14:00:00Z", "price": 45.00 }
  ]
}
curl example
curl "https://api.pocketdex.io/api/dashboard/activity?limit=10 \
  -H "Authorization: Bearer <token>"

Portfolio Analytics

Portfolio Analytics endpoints

Snapshot-driven value history, top movers, and grade/set breakdowns for the authenticated user's portfolio.

GET/api/portfolio/analytics/summary

Return total cards, total value, total cost basis, unrealized gain, ROI%, grade breakdown, and set breakdown.

No request body required.
JSON response
{
  "ok": true,
  "data": {
    "totalCards": 340,
    "totalValue": 28540.00,
    "totalCost": 18200.00,
    "unrealizedGain": 10340.00,
    "totalROI": 56.81,
    "gradeBreakdown": [{ "grade": "PSA 10", "count": 28, "value": 8400.00 }, { "grade": "Raw", "count": 290, "value": 16000.00 }],
    "setBreakdown": [{ "setName": "Scarlet & Violet", "count": 120, "value": 9600.00 }, { "setName": "Base Set", "count": 40, "value": 8750.00 }]
  }
}
curl example
curl "https://api.pocketdex.io/api/portfolio/analytics/summary \
  -H "Authorization: Bearer <token>"
GET/api/portfolio/analytics/value-history?period=30d

Return daily portfolio value snapshots for the requested period (30d, 90d, or 1yr).

No request body required.
JSON response
{
  "ok": true,
  "data": [
    { "date": "2026-04-04", "totalValue": 28540.00 },
    { "date": "2026-04-03", "totalValue": 28310.00 },
    { "date": "2026-04-02", "totalValue": 27950.00 }
  ]
}
curl example
curl "https://api.pocketdex.io/api/portfolio/analytics/value-history?period=90d \
  -H "Authorization: Bearer <token>"
GET/api/portfolio/analytics/top-movers?limit=5

Return top gainers and losers by ROI percentage across the authenticated user's portfolio.

No request body required.
JSON response
{
  "ok": true,
  "data": {
    "gainers": [{ "cardId": "sv2-1", "cardName": "Miraidon", "setName": "Paldea Evolved", "purchasePrice": 8, "currentPrice": 42, "roiPct": 425.00 }],
    "losers": [{ "cardId": "base1-4", "cardName": "Charizard", "setName": "Base Set", "purchasePrice": 1200, "currentPrice": 875, "roiPct": -27.08 }]
  }
}
curl example
curl "https://api.pocketdex.io/api/portfolio/analytics/top-movers?limit=10 \
  -H "Authorization: Bearer <token>"

Rate Limits

Plan-based request ceilings

All API requests are rate limited per token. Upgrade tiers increase throughput for integrations that need higher polling or sync volume.

PlanRequests / minuteBest for
Free100 req/minPersonal projects and light integrations
Pro500 req/minDashboards, automations, and partner tools
Dealer1000 req/minHigh-volume storefronts and sync-heavy workflows

Error Codes

Standard HTTP responses

PoketDex uses conventional HTTP status codes. Error payloads typically include a machine-readable code and a human-readable message for debugging.

400

Bad Request

The request body, query params, or path params failed validation.

401

Unauthorized

Missing token, invalid token, or expired session.

403

Forbidden

Authenticated, but the user does not have access to the requested resource.

404

Not Found

The requested record or route could not be found.

409

Conflict

The request conflicts with existing state, such as duplicate registration or RSVP.

429

Too Many Requests

The client exceeded the allowed rate limit for the active plan.

500

Internal Server Error

An unexpected server-side error occurred.

Example error response
{
  "error": {
    "code": "unauthorized",
    "message": "Bearer token is missing or invalid"
  }
}