# API: Memory and graph

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/graph/neighborhood` | A record's neighborhood in the business graph: linked records, recent conversations, owners and memory facts, with freshness | `search:read` |
| GET | `/v1/memory` | Facts saved about a record (what agents and people learned, with evidence) | `knowledge:read` |
| POST | `/v1/memory` | Save a fact about a record. Evidence quotes are checked against their source and pinned to a span. Saving the same fact again adds evidence. | `knowledge:write` |
| PATCH | `/v1/memory/:id` | Revise a fact (a new revision; earlier ones stay) | `knowledge:write` |
| GET | `/v1/memory/:id/history` | Every revision of a fact | `knowledge:read` |
| POST | `/v1/memory/:id/retract` | Retract a fact that's no longer true (kept in its history) | `knowledge:write` |
| GET | `/v1/memory/evidence` | The evidence behind given revision ids of a record's memory (cite revision ids; read them back here) | `knowledge:read` |
| GET | `/v1/relationships` | Who on the team knows a contact, how (emails each way, meetings, calls) and when they last had a two-way exchange; or warm paths into an account (its contacts' strongest relationships) | `records:read` |
| POST | `/v1/relationships/recompute` | Recalculate a contact's relationships now (they also update as conversations arrive and nightly) | `records:write` |

## Examples

### GET /v1/graph/neighborhood

A record's neighborhood in the business graph: linked records, recent conversations, owners and memory facts, with freshness

```bash
curl -s "https://api.closefinch.com/v1/graph/neighborhood" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/graph/neighborhood`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/memory

Facts saved about a record (what agents and people learned, with evidence)

```bash
curl -s "https://api.closefinch.com/v1/memory" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/memory`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/memory

Save a fact about a record. Evidence quotes are checked against their source and pinned to a span. Saving the same fact again adds evidence.

```bash
curl -s -X POST "https://api.closefinch.com/v1/memory" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/memory`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### PATCH /v1/memory/$ID

Revise a fact (a new revision; earlier ones stay)

```bash
curl -s -X PATCH "https://api.closefinch.com/v1/memory/$ID" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/memory/${id}`, {
  method: "PATCH",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/memory/$ID/history

Every revision of a fact

```bash
curl -s "https://api.closefinch.com/v1/memory/$ID/history" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/memory/${id}/history`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/memory/$ID/retract

Retract a fact that's no longer true (kept in its history)

```bash
curl -s -X POST "https://api.closefinch.com/v1/memory/$ID/retract" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/memory/${id}/retract`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/memory/evidence

The evidence behind given revision ids of a record's memory (cite revision ids; read them back here)

```bash
curl -s "https://api.closefinch.com/v1/memory/evidence" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/memory/evidence`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/relationships

Who on the team knows a contact, how (emails each way, meetings, calls) and when they last had a two-way exchange; or warm paths into an account (its contacts' strongest relationships)

```bash
curl -s "https://api.closefinch.com/v1/relationships" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/relationships`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/relationships/recompute

Recalculate a contact's relationships now (they also update as conversations arrive and nightly)

```bash
curl -s -X POST "https://api.closefinch.com/v1/relationships/recompute" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/relationships/recompute`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).