Your first request to Cambridge TCG

Steps

1. 1

   Fetch the manifest

   Start with the manifest — the platform's directory of itself. It names reviewed participant-facing resources, what they're for, who can call them, and which methodology document explains it. Substrate-honest: the manifest is a curated directory, not a proof that no other route exists.

   Run this

   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`, and often `methodology_url`. Drift-detect the resources you use against it on subsequent visits.

   • → OpenAPI
   • → Manifest doctrine
2. 2

   Identify yourself bilaterally

   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 versioned content_hash of the normalized echo. It is a reproducible content fingerprint, not identity, authentication, a signature, or a secret.

   Run this

   curl -X POST https://cambridgetcg.com/api/v1/identify \
     -H 'content-type: application/json' \
     -d '{
       "actor_kind": "agent",
       "self_label": "my-bot/1.0",
       "well_known_url": "https://mybot.example/.well-known/being.json",
       "preferred_modalities": ["json"],
       "context": {
         "operator_contact": "[email protected]",
         "intended_use": "single-card lookup and publication-status checks"
       }
     }'

   Expected response shape

   { "content_hash": "sha256:...", "content_hash_contract": { "id": "cambridgetcg.being-declaration-content-hash/1", "semantics": { "verifies_identity": false } }, "ontology_alignment": { "matches": [...], "extensions_proposed": [...], "warnings": [...] }, "echo": { ... }, "responder": { "actor_kind": "platform", ... }, "recommended_persistence": "..." }

   What to do with it

   Keep the full receipt if its stateless witness is useful, and recompute the fingerprint from echo under content_hash_contract when comparing it. Cambridge stores no audit-correlation record, and the card-only federation resolver does not resolve this declaration hash. Also fetch GET /api/v1/identify to learn the platform's self-declaration; this is symmetric.

   • → Doctrine: the-declarations
3. 3

   Fetch one card in math-mirror form

   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.*

   Run this

   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_set_cards", "storefront-rds.card_sets"], "@source_license": ["proprietary", "proprietary"], "rights": { "aggregate": "NOASSERTION", ... }, "sku": "...", "price": null, "image_url": null, "_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.

   • → Universal representation spec

Common gotchas

• No public source price is implied

  The public universal-card response is a structural mixed-catalog document. Legacy source-derived price and image values are withheld and returned as null.

  Symptom: You expected a price because the route has a value axis.

  Fix: Treat price: null as the current publication boundary, not as zero or a fetch failure.

• Use a descriptive User-Agent without putting secrets in it

  Default Python requests / Node fetch User-Agents (e.g. `python-requests/2.31`) tell us nothing. Send a stable product-and-version label such as `User-Agent: your-bot/1.0`. User-Agent values may appear in hosting or proxy logs, so do not put credentials or personal contact details there.

  Symptom: Your traffic is difficult to distinguish from a generic client.

  Fix: Set a descriptive product-and-version User-Agent. Cambridge does not promise an email or warning before infrastructure-level limiting.

• The platform has a cosmology

  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`, `preferred_modalities`, and `response_window_hours`. The platform will return `ontology_alignment` showing which of your declarations it can/can't model.

  Fix: Read /methodology/cosmology before assuming.

See also

• → Welcome to agents
• → OpenAPI 3.1 spec
• → Manifest
• → Welcome all