Kival exposes its shared application model through an HTTP API under /api/v1. The CLI and official SDKs build on the same server-side semantics for objects, versions, access, search, commentary, history, and integrations.
Base URL and authentication
For a server at:
https://kival.examplethe API root is:
https://kival.example/api/v1Programmatic requests authenticate with a bearer API key:
Authorization: Bearer <API_KEY>A key acts through its owning user. The request is bounded by the user's current authority, the key's scopes, and explicit workspace delegation for workspace-scoped routes. See Agent access for credential lifecycle.
API-key surface
The API-key-capable surface covers the major shared resources: workspaces, objects and versions, attachments, relationships and graph views, search, commentary, access management, audit events, supported global administration, and realtime invalidations.
Some personal or security-sensitive state remains browser-session-only, including passkey/session management, API-key management, workspace creation, favorites and pins, notification preferences, and the personal inbox.
Errors and pagination
JSON errors carry a stable machine-readable code alongside a human-readable message. Use HTTP status and error code for program logic rather than parsing message text.
Collection endpoints use opaque cursor pagination through items and next_cursor. Send the cursor back with the same query and filters; do not decode or construct cursors yourself. Collection responses do not promise a total count.
Rate-limited responses can include Retry-After; clients should honor it.
Optimistic object updates
Object content is versioned. An update names the exact current version it was based on through expected_current_version_id.
If another writer has already advanced the object, Kival returns a conflict. Re-read the current state, reconcile the intended change, and decide whether to submit a new update. Do not wrap the API in unconditional last-write-wins behavior.
Omitted title, body, and metadata fields inherit their current values. A semantic no-op does not append an identical version.
Events and realtime
Audit events are durable recorded activity and can be queried incrementally where authorized. Realtime is different: the authenticated /api/v1/realtime WebSocket sends invalidations that tell a client visible state may have changed.
Realtime messages can be delayed, duplicated, missed, or reordered and have no replay. Treat them as a signal to refresh authoritative HTTP state. When durable catch-up matters, use event queries and normal API reads.
Choosing raw HTTP
Use the raw API when you are integrating from a language without an official client or intentionally need transport-level control. For Rust and TypeScript, SDKs provide typed wrappers around the same contract; for shell composition, use the CLI.