Skip to main content
The REST API is one of two ways Nous exposes the v2 context graph. Reach for it when the caller already knows what to read or write, a workflow runtime fetching a filtered list of people, a form intake creating a lead, a daily job patching sent_at mid-loop. For agent-time decisions where the right action is reasoned at runtime (semantic exploration, intent-shaped context, recording an observation from open text), use the MCP server instead. Both surfaces sit on the same context graph, so a write through one is visible to the other.

​
Base URL

Self-hosting? Point at your own deployment.

​
Authentication

Every request takes a workspace API key in the Authorization header. Create one at Settings → API Keys in your workspace.
Keys are workspace-scoped, so no separate workspace ID is required.

​
The endpoints

​
Read

POST /v2/context

Engineered context for a task about one entity. The ranked, claim-tagged block your agent consumes before acting.

GET /v2/accounts/:id

The full account. Entity plus every claim with epistemics plus the recent timeline.

GET /v2/people

Filtered list of people in the workspace. Workflow shape — paginate, filter, sort.

GET /v2/leads

Filtered list of leads across lead lists. Same shape as /v2/people, with lead-specific fields.

POST /v2/query

Retrieve and summarise a corpus of observations across many entities.

POST /v2/score

Score a lead against your ICP model and intent, written into the graph. The thin verb a spreadsheet or Clay column calls per row.

GET /v2/attention

Workspace-wide. Accounts gone quiet, facts decayed, ranked decisions.

POST /v2/verify

Re-check one claim against current observations. The calibration check.

POST /v2/dedup

Cross-list cold-outbound dedup. net_new, engaged, bounced, unsubscribed.

GET /v2/workspace/facts

The user’s own GTM profile. ICP, market, pricing, competitors.

POST /v2/notes/search

Semantic search over saved notes & documents. Pull the relevant passage, not the whole document.

​
Write

POST /v2/observations

Record what happened. You observe; Nous derives the claims.

POST /v2/notes

Attach a meeting brief, transcript, or note to a contact. Append-only and dated.

POST /v2/workspace/facts

Write back a GTM section — it evolves, keeping the prior version as history.

POST + PATCH /v2/people

Create a person from a form intake. PATCH asserts fields like email, title, or company directly onto the entity.

POST + PATCH /v2/leads

Add leads to a list. PATCH a row mid-workflow to record progress before the async webhook arrives.

POST /v2/lead-lists/attach

Score a whole list you built somewhere else in one call. Nous creates the list, resolves every row, and scores it.

​
React

Triggers (outbound webhooks)

Subscribe a URL to interaction events. The instant a reply, connection accept, or meeting lands, Nous POSTs a signed payload to your workflow. The agent-gets-paged surface for the account.

​
Two write shapes, one graph

Both write paths land in the same context graph. The asserted-claim path is the deterministic shape n8n needs. The observation path is how the graph self-heals as new signals arrive. They coexist.

​
Identifiers are universal

Most endpoints accept a focus parameter (or use :id). Pass any of:
  • an entity UUID (a1b2c3d4-...)
  • an email (sarah@acme.com)
  • a domain (acme.com)
  • a LinkedIn URL (https://linkedin.com/in/sarah-chen)
  • a name (Sarah Chen)
A name may match several people. The response will be { status: "ambiguous", candidates: [...] } so your workflow can pick one and re-call.

​
Epistemics on every claim

Every claim Nous returns carries three signals so the caller can decide whether to act on it. Workflows that depend on a fact should check freshness === 'fresh' && confidence > 0.7. Anything weaker, call /v2/verify first.

​
Errors

All errors return JSON with an error code.