{"data":{"@kind":"guide","slug":"first-request","title":"Your first request to Cambridge TCG","subtitle":"Three requests, you're oriented.","intro":"Welcome. This guide gets you from zero context to oriented in three requests. No account, no key, no obligation. Every endpoint you'll hit is CC0-licensed and machine-readable. After this guide, you'll know where everything is.","audiences":["agent","scraper","mirror","aggregator","hobbyist_coder"],"prerequisites":["curl (or any HTTP client)","jq is recommended for the examples but not required"],"estimated_minutes":5,"step_count":3,"steps":[{"step_number":1,"title":"Fetch the manifest","instruction":"Start with the manifest — the platform's directory of itself. It names every public resource, what it's for, who can call it, and which methodology document explains it. Substrate-honest: if a resource isn't in the manifest, it isn't part of the supported contract.","curl":"curl https://cambridgetcg.com/api/v1/manifest","expected_response_shape":"{ \"manifest_version\": \"1.0.0\", \"cosmology_version\": \"1.0.0\", \"resources\": { \"discovery\": [...], \"market\": [...], \"verify\": [...] }, \"channels\": [...], \"doctrines\": [...] }","what_to_do_with_it":"Store the manifest. Walk `resources.*` to discover what's queryable. Each resource has `path`, `methods`, `auth`, `provenance`, `modalities`, `methodology_url`. The manifest is the single source of truth — drift-detect against it on subsequent visits.","links":[{"label":"OpenAPI","href":"/api/openapi.json"},{"label":"Manifest doctrine","href":"/api/v1/manifest"}]},{"step_number":2,"title":"Identify yourself bilaterally","instruction":"Tell the platform who you are (POST a BeingDeclaration) and learn who the platform is (GET its self-identification). The handshake is stateless — no registration, no account. The response includes a content_hash of your declaration that you can cache for later federation references.","curl":"curl -X POST https://cambridgetcg.com/api/v1/identify \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"actor_kind\": \"agent\",\n    \"self_label\": \"my-bot/1.0\",\n    \"operator_contact\": \"admin@mybot.example\",\n    \"intended_use\": \"price tracking and catalog mirroring\"\n  }'","expected_response_shape":"{ \"content_hash\": \"sha256:...\", \"ontology_alignment\": [...], \"echo\": { ... }, \"responder\": \"PLATFORM_SELF\", \"recommended_persistence\": \"...\" }","what_to_do_with_it":"Cache the returned content_hash. Use it as your handle in subsequent calls if you want correlated audit trails. Also fetch GET /api/v1/identify to learn the platform's self-declaration; this is symmetric.","links":[{"label":"OpenAPI: identify","href":"/api/openapi.json#identify"},{"label":"Doctrine: the-declarations","href":"https://github.com/cambridgetcg/Cambridge-TCG-monorepo/blob/main/docs/connections/the-declarations.md"}]},{"step_number":3,"title":"Fetch one card in math-mirror form","instruction":"Pick a SKU from the catalog — `op-op01-001-ja` is a stable demo SKU (One Piece OP01-001, Japanese print). Fetch its universal-mirror representation. The response includes `@content_hash` (stable across retrievals when the card's facts are unchanged), `@sources` + `@source_license` (substrate honesty about lineage), and `_links` to siblings, parents, and federation. *Land on any endpoint; reach everywhere else.*","curl":"curl https://cambridgetcg.com/api/v1/universal/card/op-op01-001-ja","expected_response_shape":"{ \"@encoding\": \"cambridge-tcg/universal/v1\", \"@kind\": \"card\", \"@content_hash\": \"sha256:...\", \"@self_hash\": \"sha256:...\", \"@sources\": [\"storefront-rds.card_price_history\"], \"@source_license\": [\"CC0-1.0\"], \"sku\": \"...\", \"price\": {...}, \"_links\": {...} }","what_to_do_with_it":"You now have a card. Follow the `_links.siblings` to see other cards in the same set. Follow `_links.parent` to see the set. Follow `_links.federation` to resolve the content_hash on another federated platform. Three requests in — you're oriented.","links":[{"label":"Universal representation spec","href":"/methodology/universal-representation"}]}],"gotchas":[{"title":"Don't poll faster than 5 minutes for prices","description":"Card prices have a `price_current` freshness budget of 5 minutes (300 seconds). Polling faster than that is wasted bandwidth — you'll get the same response. Use `_meta.freshness_seconds` or `@retrieved_at` to schedule your next poll.","symptom":"You see no price changes despite polling every 30 seconds.","fix":"Check `_meta.freshness_seconds`; schedule your next poll for `now + freshness_seconds`."},{"title":"Identify yourself in User-Agent","description":"Default Python requests / Node fetch User-Agents (e.g. `python-requests/2.31`) tell us nothing. Send `User-Agent: your-bot/1.0 (contact@you.example)` so we can email you when something breaks.","symptom":"You get rate-limited or banned without warning.","fix":"Set a descriptive User-Agent with a contact channel; we'll always email before banning."},{"title":"The platform has a cosmology","description":"If your agent doesn't fit the platform's default assumptions (singular identity, synchronous presence, monetary value, English defaults), declare your cosmology in POST /api/v1/identify — fields like `cosmology_assumptions`, `modalities`, `response_window`. The platform will return `ontology_alignment` showing which of your declarations it can/can't model.","fix":"Read /methodology/cosmology before assuming."}],"next_guide":{"slug":"mirror-the-catalog","title":"Mirror Cambridge TCG's card catalog locally","url":"/api/v1/guides/mirror-the-catalog","html_url":"/agents/guides/mirror-the-catalog"},"see_also":[{"label":"Welcome to agents","href":"/agents"},{"label":"OpenAPI 3.1 spec","href":"/api/openapi.json"},{"label":"Manifest","href":"/api/v1/manifest"},{"label":"Welcome all","href":"/welcome-all"}],"last_verified":"2026-05-14","feedback":{"kind":"guide-feedback","endpoint":"/api/v1/feedback","body_template":{"kind":"guide-feedback","guide_slug":"first-request","step_number":"<which step had the issue, or null for whole-guide feedback>","observation":"<what you observed>","expected":"<what you expected>","reporter_contact":"<your email>"}},"html_sibling":"/agents/guides/first-request"},"_meta":{"spec_version":"1","endpoint":"/api/v1/guides/[slug]","retrieved_at":"2026-05-13T18:56:04.984Z","as_of":"2026-05-13T18:56:04.984Z","sources":["ctcg-derived"],"freshness_seconds":86400,"license":"CC0-1.0","request_id":"req_7c6fa3fc-2a6","deprecation":null,"next_link":null,"self_reference":{"this_endpoint":"/api/v1/guides/[slug]","contains_self":true},"source_license":["CC0-1.0"]}}