Skip to content
SilphCo

Card Research API

On-demand multi-lane market research with daily timeseries export

Last updated:

On this page

The Card Research API runs fresh marketplace scrapes for a single Pokémon TCG card — eBay sold listings, TCGPlayer, Mercari, and other lanes — then returns a daily per-marketplace timeseries. Jobs are asynchronous: submit, poll until completed, then download CSV.

Base URL: https://silphcoanalytics.xyz/api/v3. Contract: lor-api-research.v1. Stability: beta.

Authentication

Same as other v3 endpoints: pass your API key as a Bearer token. Get a free key at the dashboard.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://silphcoanalytics.xyz/api/v3/cards/sv5-204/research

Workflow

  1. POST /cards/{card_id}/research — enqueue a scrape (or reuse fresh gold data when available).
  2. GET /research/{job_id} — poll until status is completed or failed.
  3. GET /research/{job_id}/timeseries.csv — download the daily marketplace timeseries.

Live scrapes can take several minutes. Poll every 5–10 seconds. A 48-hour cooldown applies per card+grade unless force_refresh is true (returns HTTP 429 when still cooling down).

Submit a job

POST /api/v3/cards/{card_id}/research

Request body

{
  "grades": ["Near Mint"],
  "lanes": [],
  "force_refresh": false
}

grades scopes the condition (e.g. "Near Mint", "PSA 10"). Empty lanes uses all default marketplaces. Only stale or missing lanes are scraped; fresh data is reused.

Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grades":["PSA 10"]}' \
  https://silphcoanalytics.xyz/api/v3/cards/sv5-204/research

Response (envelope)

{
  "ok": true,
  "contract": "lor-api-research.v1",
  "data": {
    "job_id": "abc123",
    "status": "running",
    "phase": "ebay",
    "reused": false,
    "scope": {
      "pokemontcg_id": "sv5-204",
      "grades": ["PSA 10"],
      "lanes": ["ebay", "tcgplayer", "mercari"]
    },
    "result_summary": {},
    "error": null
  }
}

Poll status

GET /api/v3/research/{job_id}

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://silphcoanalytics.xyz/api/v3/research/abc123

When status is completed, check result_summary for row counts and lane coverage. On failure, error describes what went wrong.

Download results

Timeseries CSV — one row per (date, marketplace) with sale counts and price stats:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -o sv5-204-timeseries.csv \
  https://silphcoanalytics.xyz/api/v3/research/abc123/timeseries.csv

Columns include:

  • pokemontcg_id, grade_key, marketplace, date
  • sale_count, avg_price_usd, min_price_usd, max_price_usd, total_volume_usd

Raw per-sale rows are also available at GET /research/{job_id}/sales?format=csv or format=parquet once the job completes.

Chat interface

The same research engine powers Silph Agent chat. Send a message like research sv5-204 in PSA 10 to POST /api/v3/agent/chat (SSE stream). The agent resolves the card, runs research, narrates findings, and emits a downloadable result handle. Use the REST endpoints above when you want direct programmatic control without the LLM layer.