Cobenian Oversight REST API

Programmatic access to your business monitoring data.

Authentication

All API requests require a Bearer token. Generate an API key in Settings → API Keys in the Oversight dashboard.

curl -H "Authorization: Bearer ovst_your_key_here" \
  https://oversight.cobenian.com/api/v1/items

API keys are scoped to your account. All data returned is limited to your account only.

Rate Limits

100 requests per minute per API key. When exceeded, you'll receive a 429 Too Many Requests response.

Response Format

All responses return JSON. List endpoints return:

{"data": [...], "meta": {"total": 29}}

Single resource endpoints return:

{"data": {...}}

Errors return:

{"error": {"code": "unauthorized", "message": "Invalid API key"}}

Permissions

Each API key has specific permissions. Available permissions:

Permission	Grants access to
read:clients	List and view clients
read:events	List calendar events
read:invoices	List invoices
read:team	List team members
read:hypotheses	List and view planner hypotheses
write:hypotheses	Approve or dismiss hypotheses
read:actions	List and view actions
read:signals	List and view signals
read:objectives	List and view objectives
read:wiki	List and view wiki/KB entries
write:wiki	Create, edit, and delete KB entries
write:assistant	Use the AI assistant

Core Data

GET /api/v1/clients

List clients with health scores.

Parameter	Type	Description
confirmed	boolean	Filter by confirmed status (default true)

GET /api/v1/clients/:id

Get a single client with health score breakdown.

GET /api/v1/events

List upcoming calendar events.

Parameter	Type	Description
limit	integer	Max results (default 20, max 100)

GET /api/v1/invoices

List invoices.

Parameter	Type	Description
status	string	Filter by status: sent, paid, overdue
client_id	integer	Filter by client
limit	integer	Max results (default 25, max 100)

GET /api/v1/team

List team members.

POST /api/v1/assistant/ask

Ask the AI assistant a question about your business data. Requires write:assistant permission.

curl -X POST -H "Authorization: Bearer ovst_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "Which clients have overdue invoices?"}' \
  https://oversight.cobenian.com/api/v1/assistant/ask

---

Planner

Hypotheses, actions, signals, and objectives.

GET /api/v1/hypotheses

List open hypotheses. Requires read:hypotheses.

limit

integer

Max results (default 20)

GET /api/v1/hypotheses/:id

Get a single hypothesis by ID.

POST /api/v1/hypotheses/:id/approve

Approve a hypothesis — resolves it positively and executes all pending actions. Requires write:hypotheses.

POST /api/v1/hypotheses/:id/dismiss

Dismiss a hypothesis. Requires write:hypotheses.

GET /api/v1/actions

List recent actions (newest first). Requires read:actions.

limit

integer

Max results (default 20)

GET /api/v1/actions/:id

Get a single action by ID.

GET /api/v1/signals

List unprocessed signals. Requires read:signals.

limit

integer

Max results (default 20)

GET /api/v1/signals/:id

Get a single signal by ID with its payload.

GET /api/v1/objectives

List active business objectives. Requires read:objectives.

GET /api/v1/objectives/:id

Get a single objective by ID.

Knowledge base

GET /api/v1/wiki

List wiki/KB entries (playbooks, observations, baselines, hand-typed facts). Requires read:wiki.

Parameter	Type	Description
client_id	integer	Optional — scope results to a specific client.

POST /api/v1/wiki

Create a new KB entry under an atomic (non-aggregate) topic. Reserved aggregate index topics are refused. Requires write:wiki.

Field	Type	Description
topic	string	Required. Topic path for the new entry.
content	string	Required. Entry content (markdown allowed).
tags	array	Optional initial tags. kind:guidebook is added automatically.

PUT /api/v1/wiki/:id

Replace the content of an existing KB entry. Reserved index topics refused. Requires write:wiki.

Field	Type	Description
new_content	string	Required. Replacement content.

DELETE /api/v1/wiki/:id

Delete a KB entry by id. Reserved index topics refused. Requires write:wiki.