Quickstart

This walks you from zero to your first authenticated response.

1. Get an API key

API keys are self-serve from your PikaQian account:

1. Sign in at pikaqian.com.
2. Go to Account → API keys.
3. Create a key. It looks like pk_live_… — copy it now; the secret is shown only once.

New accounts start on the free tier (metadata only). To unlock pricing and sales, upgrade on the pricing page. See Tiers & rate limits for what each tier includes.

2. Make a request

Send your key in the X-API-Key header on every request:

curl https://api.pikaqian.com/v1/sets \
  -H "X-API-Key: pk_live_your_key_here"

import requests

resp = requests.get(
    "https://api.pikaqian.com/v1/sets",
    headers={"X-API-Key": "pk_live_your_key_here"},
)
resp.raise_for_status()
print(resp.json()["data"][0])

const resp = await fetch("https://api.pikaqian.com/v1/sets", {
  headers: { "X-API-Key": "pk_live_your_key_here" },
});
const body = await resp.json();
console.log(body.data[0]);

A list response wraps results in data with a pagination block:

{
  "data": [
    {
      "id": "csv6c",
      "name": "Mask of Change",
      "local_name": "假面的化身",
      "series": "ScarletViolet",
      "release_date": "2024-03-22",
      "card_count": { "actual": 106 },
      "pack_image_url": "https://images.pikaqian.com/sets/packs/csv6c.webp"
    }
  ],
  "pagination": { "next_cursor": "eyJrIjoiMjAyMC0w…", "page_size": 50 }
}

3. Fetch a card

curl "https://api.pikaqian.com/v1/cards?set_id=csv6c&name_contains=pikachu" \
  -H "X-API-Key: pk_live_your_key_here"

Take a card id from the results and fetch its detail:

curl https://api.pikaqian.com/v1/cards/9e0546b4-cb8f-452d-9e73-ecc3a4fcd21f \
  -H "X-API-Key: pk_live_your_key_here"

On a paid tier the prices field is populated; on free it's null but the rest of the card (including image_url) is returned. Image URLs point at our public CDN and are fetchable without a key.

The detail also carries the printed card text on every tier — HP, type, weakness, retreat cost, attacks, abilities, rule text, illustrators — in Chinese verbatim (keys holding Chinese text are local_-prefixed). For the card above, csv6c 001 溜溜糖球 / Surskit:

{
  "hp": 50,
  "local_element": "草",
  "local_subtypes": [],
  "weaknesses": [{ "local_type": "火", "value": "×2" }],
  "resistances": [],
  "retreat_cost": 1,
  "attacks": [
    {
      "kind": "attack",
      "local_name": "三重旋转",
      "local_text": "抛掷3次硬币，造成正面次数×10伤害。",
      "local_cost": ["草"],
      "damage": "10×"
    }
  ],
  "abilities": [],
  "local_rules": [],
  "local_flavor_text": "从头顶分泌出的液体有着如同麦芽糖浆的甜味。住在有大量水草的池塘里。",
  "regulation_mark": "G",
  "illustrators": ["Yoriyuki Ikegami"]
}

See Best practices → Chinese card text for how to read the inline 【…】 tokens, + costs, and [] vs null.

Next steps

• Authentication — key handling and errors.
• Tiers & rate limits — what each tier unlocks and how to read the rate-limit headers.
• API Reference (in the sidebar) — every endpoint, parameter, and response schema, with an interactive "try it" console.