API overview
Authentication, resources and conventions.
The Cogna8 API is a JSON over HTTPS API with four resources. Agents record the facts they rely on, ask the gate before consequential actions, and read the history. Webhooks push events to you.
| Resource | Endpoint | Purpose |
|---|---|---|
| State | POST /v1/state/items | Record a fact as governed state |
| Gate | POST /v1/gates/evaluate | Ask whether an action may run |
| History | GET /v1/history/events | Query state changes and decisions |
| Webhooks | POST /v1/webhooks | Subscribe to events |
Authentication
Send your secret key as a bearer token on every request. Keys are issued per workspace.
Authorization: Bearer sk_live_...Conventions
| Convention | Detail |
|---|---|
| Sessions | A session_id groups the state and decisions of one conversation, case or task |
| IDs | Prefixed by type: si_ for state items, gd_ for gate decisions, ev_ for events |
| Times | ISO 8601 in UTC, for example 2026-09-15T04:23:07Z |
| Paging | List endpoints return has_more and a cursor to pass back |
| Base URL | Provided with your workspace credentials |
Last reviewed October 2026Suggest a change