API reference

All 50 endpoints, grouped by purpose. Guides lead, this is the reference.

Complete endpoint reference for the COHESION Judgment Independence Score API. If you are just starting, read the guides first. The reference is here for when you need the exact wire shape.

Base URL: https://api.cohesionauth.com. All endpoints return JSON. Every response includes request_id and timestamp.

Meta

Scoring

All scoring endpoints authenticate via X-API-Key: ck_live_<26-char> (the per-org key issued at signup or via key rotation).

Admin (per-org self-serve)

These endpoints authenticate via the org’s own X-API-Key. Every action is audit-logged to the org’s own audit_log.

Admin (master-key — added 2026-05-02)

Nine endpoints added in the 2026-05-02 additive authorization bundle. These authenticate via the endpoint’s OWN scoped Cloudflare Secret (MASTER_ADMIN_KEY_*) — NOT the per-org X-API-Key. Each handler reads ONLY its scope’s secret per defense-in-depth (D15). Layer 2 rate limit bypassed; Layer 1 per-IP enforced. No X-RateLimit-Limit header on these endpoints (avoids leaking the bypass).

Caller split:

• payment-worker (Stripe self-serve onboarding) holds 4 secrets and can call the first 4 endpoints below
• admin-worker (internal admin dashboard) holds 5 secrets and can call the last 5 endpoints below
• scoring-api validates all 9 master keys (it is the validator side of the contract)
• Cross-worker compromise blast radius is bounded per endpoint
• Global uniqueness invariant: every active and previous value across all MASTER_ADMIN_KEY_* scopes (and across both workers’ rotation lists) MUST be globally unique. Provisioning verifies uniqueness BEFORE wrangler secret put. Duplicate values across scopes collapse the per-endpoint authorization model and are a deploy-blocking misconfiguration.

Idempotency contract: the 8 mutating endpoints accept Idempotency-Key: <stripe-event-id-or-uuid> header. Replays return the cached envelope (sanitized — plaintext keys NEVER cached; replays of org/create, billing/rotate, or force-rotate return prefix + already_provisioned: true only, and the original caller had ONE chance to capture the plaintext from the first response). The composite primary key on admin_action_idempotency is (endpoint, idempotency_key) per Codex P1-16 — prevents cross-endpoint replay where a key minted for one endpoint could be replayed against another.

Read endpoint exemption: GET /v1/admin/org/{org_id}/usage is read-only and skips the idempotency cache.

Postman collection: the new “Admin (master-key)” folder in api/postman/cohesion-api.postman_collection.json covers all 9 endpoints with sample requests + responses. Set scope-specific {{master_admin_key_*}} env variables (NOT {{api_key}}) to avoid sending a per-org key to a master-auth endpoint.

Public demo

Interactive playground

All endpoints can be called from the playground with your own API key.

Error shape

Uniform K8 v2 envelope:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "modification_extent must be between 0.0 and 1.0",
    "request_id": "req_01H...",
    "timestamp": "2026-04-22T18:22:10.432Z"
  }
}

See the full error catalog.