API Conventions

Base URL

https://your-tenant.cognethics.com

REST endpoints live under /api/v1/…; a few application prefixes are unversioned. Paths are stable either way — the documented path is the contract.

Authentication

Send Authorization: Bearer <key> on every REST and MCP call. The key can be a ck_… API key, an mcp_… key, or an OAuth access token. JWT access tokens last 15 minutes; refresh tokens last 1 day.

Send X-Organization-Context: <organization UUID> to scope a call to a specific organization inside your tenant. Omit it and the call scopes to your last-selected organization, then your home organization. A UUID you can't access returns 403.

Pagination

List endpoints accept ?page= and ?page_size= (default 20, max 100). The response carries:

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": [],
  "current_page": 1,
  "total_pages": 0,
  "page_size": 20,
  "has_next": false,
  "has_previous": false,
  "start_index": 0,
  "end_index": 0
}

An out-of-range page returns 404 with "Invalid page number".

Filtering, search, ordering

List endpoints accept ?<field>= filters specific to that resource, plus ?search= (free text) and ?ordering=<field> or ?ordering=-<field> (descending) across every list endpoint.

Timestamps

Every timestamp is ISO-8601 UTC with a trailing Z.

Retries and idempotency

GET, HEAD, and OPTIONS are safe to retry freely. PUT and DELETE are idempotent by construction. For POST, honor Retry-After and read back the resource before assuming a retry didn't already create it — some write endpoints require an Idempotency-Key header and answer 428 without one; an endpoint that requires it says so in its own reference entry.

Response headers

Every response carries X-Response-Time.