MarketSchema Research Evidence API v1

Send your per-customer key in the X-API-Key header. Keys carry scopes; the server stores only a hash. Configured key records must include a stable id and 64-character key_sha256; malformed records and duplicate key IDs are ignored fail-closed so rate and quota buckets never share an anonymous identity.

GET /api/customer/usage
  -> { contract_version: "customer_usage.v1", generated_at, customer, scopes, usage, limits, remaining, billing }

GET /api/research/public/hub-pit-identity-cohort/v1
  -> { schema: "marketschema.research.hub_pit_identity_cohort.v1", status, as_of, as_known_at, source_inputs, coverage, baskets, bindings, typed_pending_bindings, prospective_hypothesis_bindings, consumer_views, boundary }

RETIRED DCO READS — 410 + Cache-Control: no-store
GET /api/research/v1/dossiers/{ticker}
GET /api/research/v1/ticker/{ticker}/latest
GET /api/research/v1/dossier/{run_id}
GET /api/research/v1/ticker/{ticker}/history
GET /api/research/v1/evidence-delta?symbols=NVDA,AMD
POST /api/research/v1/digs
GET /api/research/v1/digs/{batch_id}
  -> 410 typed retirement before auth/body/query/storage/billing/provider/model work; every response points to /api/research/public/hub-pit-identity-cohort/v1 and exports no score or rank

Record the exact version of the contract you poll. The live Hub identity cohort is a distinct marketschema.research.hub_pit_identity_cohort.v1 packet. It carries exact Asset, Basket, PRIMARY/CONTEXT role, effective/known-at, revision, and typed pending/unavailable identity without a Research score or rank. Ticker/run DCO, Evidence Delta, and dig routes are retired typed 410 endpoints.

Historical schemas and commission helpers remain tracked for decoding old receipts, but they are not mounted as a current packet-return or compute product. A successor must admit an exact Hub Asset, issuer, and PIT Basket revision before any stored evidence or fresh compute can be served.

Retired DCO reads return 410 with Cache-Control: no-store before API-key, limit, query, archive, or serializer work. The public Hub identity cohort is also always no-store. Active customer-specific contract responses use Cache-Control: private, no-store, max-age=0 with Vary: X-API-Key.

The old ticker/run dossier mounts cannot prove exact Hub Asset plus point-in-time Basket identity for stored rows. They fail closed before auth or storage and direct consumers to the governed Hub identity cohort; ticker text is never promoted into an identity join.

/api/research/v1/evidence-delta, POST /api/research/v1/digs, and GET /api/research/v1/digs/{batch_id} are unavailable until their rows carry exact Hub identity and PIT Basket membership. Historical serializers remain unmounted compatibility code.

Active API-key endpoints return X-RateLimit-Limit/Remaining/Reset (per minute) and X-Quota-Limit/Remaining (per day). Exceeding either returns 429 with Retry-After. Retired Research evidence/compute routes bypass auth and limits and always return typed 410. /api/customer/usage remains a read-only limiter snapshot.

Production quotas can use shared Supabase api_usage via RESEARCH_RATE_LIMIT_STORE=supabase; if that configured store is unavailable, routes fail closed with 503 rate_limit_unavailable.

curl -H "X-API-Key: $MS_KEY" \
  "https://research.marketschema.com/api/customer/usage"

curl \
  "https://research.marketschema.com/api/research/public/hub-pit-identity-cohort/v1"