REST API - OpenNous

Base URL

https://api.opennous.cloud

Self-hosted instances serve the same paths from their own API URL.

Authentication

Send a workspace API key on every request. Create one in Settings → API keys. A key belongs to one workspace, so there is no workspace ID to pass.

curl https://api.opennous.cloud/v2/attention \
  -H "Authorization: Bearer $NOUS_API_KEY"

curl https://api.opennous.cloud/v2/attention \
  -H "X-API-Key: $NOUS_API_KEY"

Call the API from a server. Browser requests are blocked by CORS.

Read-only keys

A read-only key can call every GET endpoint plus POST /v2/context, POST /v2/query, and POST /v2/score. Anything else returns 403 read_only_key.

Member keys

A key created by a workspace member acts as that member. On a closed workspace it only sees accounts in that member’s book. A workspace key sees everything.

Conventions

Lists return { <items>, limit, offset, has_more }. limit defaults to 50 with a max of 200. List people without include=all keeps its own default of 100 and max of 1000. Page with offset until has_more is false.
Unknown query parameters return 400 unknown_query_param with the supported list. A filter is never silently ignored.
Admin-only routes, such as inviting or removing members, return 403 admin_key_required to a member key.
A member key’s book. On a closed workspace a member key sees only its own accounts. A record outside that book returns 404, the same as one that does not exist.

Identifying an account

Endpoints that take focus or an :id accept an email, a LinkedIn URL, a domain, or an entity UUID. Pass one of those, never a bare name. Deal endpoints and get context also take a deal id. When an identifier matches more than one record, the response is 200 with the candidates. Call again with the entity_id you want.

{
  "status": "ambiguous",
  "candidates": [
    { "entity_id": "9b2f6c1e-4d3a-4f7e-9a51-2c8d7e3b1f40", "name": "Sarah Chen", "detail": "VP Sales at Acme", "matched_on": "exact" }
  ]
}

Errors

Errors return JSON with a machine code in error. Some add detail or other fields.

{ "error": "invalid_api_key" }

Status	`error`	When
400	varies	A parameter is missing or invalid. Each endpoint lists its codes.
401	`api_key_required`	No key on the request.
401	`invalid_api_key`	The key is unknown or revoked.
401	`api_key_expired`	The key has expired. Rotate it.
402	`upgrade_required`	The workspace is past its plan limit and grace period. `reason` is `ops_limit_reached` or `active_accounts_limit_reached`.
402	`feature_not_in_plan`	The endpoint needs a feature your plan does not include.
403	`read_only_key`	A read-only key called a write endpoint.
403	`admin_key_required`	A member key called an admin-only endpoint.
404	`entity_not_found`, `person_not_found`, `deal_not_found`, …	Nothing matches, or the record is outside a member key’s book.
404	`not_found`	The path does not exist.
429	`rate_limited`	Too many requests.
500	`internal_error`	Something failed on our side.

Rate limits

Each key gets 600 requests per minute. Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Past the limit, requests return 429 until the window resets.

Endpoints

Group	Endpoints
People	`GET /v2/people` · `GET /v2/people/:id`
Accounts	`GET /v2/accounts` · `GET /v2/accounts/:id` · `POST /v2/context` · `POST /v2/query`
Deals	`GET /v2/deals` · `GET /v2/deals/:id` · `GET /v2/pipelines`
Notes	`POST /v2/notes` · `GET /v2/notes`
Attention	`GET /v2/attention`
Insights	`GET /v2/insights` · `POST /v2/insights`
Enrich & score	`POST /v2/people/:id/enrich` · `POST /v2/score`
Organization	`GET /v2/workspace/whoami` · members · brain · ICP
Workflows (beta)	`/v2/workflows`
Webhooks	Overview · `/v2/webhooks` · events
Usage	`GET /v2/usage` · `GET /v2/usage/breakdown`

Agents can reach the same graph through the MCP server.

​Base URL

​Authentication

​Read-only keys

​Member keys

​Conventions

​Identifying an account

​Errors

​Rate limits

​Endpoints