Skip to content

Getting Started with the C.O.S. API

C.O.S. API v1 — Compliance Operating System
Base URL: https://cosprotocol.io/v1

What is C.O.S.?

The Compliance Operating System (C.O.S.) is a governed REST API for compliance intelligence and organisation management. It provides structured endpoints for managing tenant organisations, their members, API keys, and industry classification.

Prerequisites

  • A C.O.S. API key — format: cos_live_<48 chars> (57 characters total)
  • Keys are currently issued by the C.O.S. administrator. Contact your C.O.S. operator to request one.

Step 1 — Verify the API is reachable

No key required:

curl https://cosprotocol.io/v1/health

{"status": "ok", "timestamp": "2026-06-10T12:00:00Z"}

Step 2 — Make an authenticated request

Pass your key in the Authorization header:

export COS_API_KEY="cos_live_your_key_here"
export ORG_ID="your-organisation-uuid"

curl -s \
  -H "Authorization: Bearer $COS_API_KEY" \
  https://cosprotocol.io/v1/organisations/$ORG_ID

import requests

API_KEY = "cos_live_your_key_here"
ORG_ID  = "your-organisation-uuid"
BASE    = "https://cosprotocol.io/v1"

resp = requests.get(
    f"{BASE}/organisations/{ORG_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
resp.raise_for_status()
print(resp.json())

If your key is valid you will receive a 200 response with your organisation profile. If the key is missing or wrong you will receive 401 Unauthorized.

Key concepts

Organisation scope. Every API key is tied to one organisation. A standard key can only read and write data for its own organisation. Keys issued for a platform organisation (is_system: true) grant cross-tenant admin access and are used by C.O.S. operators only.

Key prefix. Production keys start with cos_live_. Test keys start with cos_test_. Both prefixes are registered with GitHub secret scanning — accidental commits are detected automatically. Both prefix types have identical behaviour; the distinction is for key management and scanning rules only.

Raw key shown once. The full raw key is returned in the issuance response exactly once. It cannot be retrieved again. Store it immediately in a secrets manager.

Pagination. All list endpoints return { "data": [...], "meta": { "next_cursor": "..." } }. Pass ?cursor=<value> to fetch the next page. next_cursor is null on the last page.

Rate limits. Authenticated requests are limited to 60 per minute per organisation by default. Unauthenticated endpoints (/health, /version) share a global limit of 60 per minute. Exceeded limits return 429 with a Retry-After header.

Next steps