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 customer graph, so a write through one is visible to the other.
Base URL
Authentication
Every request takes a workspace API key in theAuthorization header. Create one at Settings → API Keys in your workspace.
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 Record. 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.
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.
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 Record.
Two write shapes, one graph
Both write paths land in the same customer graph.| Path | What it writes | When to use |
|---|---|---|
POST /v2/observations | An immutable event or state observation; Nous re-derives the claim from the full history | The agent has just seen something happen; an integration is mirroring activity from another system |
PATCH /v2/people / PATCH /v2/leads | An asserted claim (sticky, confidence 1.0) directly on the entity; the derivation engine will not overwrite it | A workflow runtime is setting a field as ground truth (enrichment result, manual edit, form value) |
Identifiers are universal
Most endpoints accept afocus 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)
{ 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.| Field | Values | Meaning |
|---|---|---|
freshness | fresh / aging / suspect / expired | How recently it was observed |
confidence | 0.0 – 1.0 | How strongly the observations support it |
epistemic_class | observed / derived / asserted | Where the claim came from |
freshness === 'fresh' && confidence > 0.7. Anything weaker, call /v2/verify first.
Errors
All errors return JSON with anerror code.
| Status | Error | What to do |
|---|---|---|
| 400 | focus_required, invalid_focus, etc. | Missing or malformed parameter |
| 401 | unauthorized | API key missing or invalid |
| 402 | feature_not_in_plan | Upgrade. Visible on the Usage page |
| 404 | entity_not_found | Focus did not match any entity |
| 413 | too_many | Reduce batch size |
| 429 | rate_limited | Honor Retry-After |
| 500 | internal_error | Retry with backoff |