> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opennous.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> The deterministic surface for workflow runtimes. Call it from n8n, Make, Zapier, or any backend. Parameters are known up front; responses are stable rows.

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](/mcp/introduction) instead. Both surfaces sit on the same context graph, so a write through one is visible to the other.

## Base URL

```
https://api.opennous.cloud
```

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.

```bash theme={null}
curl https://api.opennous.cloud/v2/attention \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

Keys are workspace-scoped, so no separate workspace ID is required.

## The endpoints

### Read

<CardGroup cols={2}>
  <Card title="POST /v2/context" href="/public-api/context" icon="brain">
    Engineered context for a task about one entity. The ranked, claim-tagged block your agent consumes before acting.
  </Card>

  <Card title="GET /v2/accounts/:id" href="/public-api/accounts" icon="user">
    The full account. Entity plus every claim with epistemics plus the recent timeline.
  </Card>

  <Card title="GET /v2/people" href="/public-api/people" icon="users">
    Filtered list of people in the workspace. Workflow shape — paginate, filter, sort.
  </Card>

  <Card title="GET /v2/leads" href="/public-api/leads" icon="list">
    Filtered list of leads across lead lists. Same shape as `/v2/people`, with lead-specific fields.
  </Card>

  <Card title="POST /v2/query" href="/public-api/query" icon="magnifying-glass">
    Retrieve and summarise a corpus of observations across many entities.
  </Card>

  <Card title="POST /v2/score" href="/public-api/score" icon="gauge-high">
    Score a lead against your ICP model and intent, written into the graph. The thin verb a spreadsheet or Clay column calls per row.
  </Card>

  <Card title="GET /v2/attention" href="/public-api/attention" icon="bell">
    Workspace-wide. Accounts gone quiet, facts decayed, ranked decisions.
  </Card>

  <Card title="POST /v2/verify" href="/public-api/verify" icon="shield-check">
    Re-check one claim against current observations. The calibration check.
  </Card>

  <Card title="POST /v2/dedup" href="/public-api/dedup" icon="filter">
    Cross-list cold-outbound dedup. net\_new, engaged, bounced, unsubscribed.
  </Card>

  <Card title="GET /v2/workspace/facts" href="/public-api/gtm-profile" icon="book">
    The user's own GTM profile. ICP, market, pricing, competitors.
  </Card>

  <Card title="POST /v2/notes/search" href="/public-api/notes-search" icon="file-magnifying-glass">
    Semantic search over saved notes & documents. Pull the relevant passage, not the whole document.
  </Card>
</CardGroup>

### Write

<CardGroup cols={2}>
  <Card title="POST /v2/observations" href="/public-api/observations" icon="pen">
    Record what happened. You observe; Nous derives the claims.
  </Card>

  <Card title="POST /v2/notes" href="/public-api/notes" icon="note-sticky">
    Attach a meeting brief, transcript, or note to a contact. Append-only and dated.
  </Card>

  <Card title="POST /v2/workspace/facts" href="/public-api/gtm-profile#writing-back" icon="book-open">
    Write back a GTM section — it evolves, keeping the prior version as history.
  </Card>

  <Card title="POST + PATCH /v2/people" href="/public-api/people/create" icon="user-plus">
    Create a person from a form intake. PATCH asserts fields like email, title, or company directly onto the entity.
  </Card>

  <Card title="POST + PATCH /v2/leads" href="/public-api/leads/create" icon="square-plus">
    Add leads to a list. PATCH a row mid-workflow to record progress before the async webhook arrives.
  </Card>

  <Card title="POST /v2/lead-lists/attach" href="/public-api/leads/attach" icon="table-list">
    Score a whole list you built somewhere else in one call. Nous creates the list, resolves every row, and scores it.
  </Card>
</CardGroup>

### React

<CardGroup cols={1}>
  <Card title="Triggers (outbound webhooks)" href="/public-api/triggers/introduction" icon="bolt">
    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.
  </Card>
</CardGroup>

## Two write shapes, one graph

Both write paths land in the same context 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) |

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.

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

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.

```json theme={null}
{ "error": "entity_not_found" }
```

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