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
`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.