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

# Lattice API

> Match incoming rows against a graph, look up records by your own ID, write labels, and follow changes.

Use Lattice to check whether an incoming row matches someone already in your graph. If you know the record ID, you can look it up directly to see its labels and connections.

## Graphs

| Method and path | Result |
| - | - |
| `GET /lattice/graphs` | Lists the graphs your team can read. Pass `next_cursor` back as `cursor` for the next page. |
| `POST /lattice/graphs` | Creates an empty graph from `{"name":"applications"}`. Returns HTTP 201 and the graph. |
| `GET /lattice/graphs/{graph_id}` | Returns the graph's name, node count, update time and build status. |
| `PATCH /lattice/graphs/{graph_id}` | Renames the graph using the same request body as creation. The graph ID stays the same. |

A graph node can represent a person, an email address or another entity, so `nodes` counts more than input rows. To add rows, connect your workflow's output to a Lattice block that targets the graph. [Build a graph from workflow output](https://docs.sixtyfour.ai/lattice/getting-started.md)

## Match an incoming row

`POST /lattice/graphs/{graph_id}/match` finds earlier records that resemble the supplied row. Use the original workflow's column names in `fields`. Supply the values you have, including full text for columns such as a bio. Lattice ignores unknown or unsearchable columns. Matching is read-only.

Set `SIXTYFOUR_API_KEY` to a key from the graph's team and `GRAPH_ID` to its ID. This example assumes the graph was built from rows with an `email` column.

```bash theme={null}
GRAPH_URL="https://api.sixtyfour.ai/lattice/graphs/$GRAPH_ID"
MATCH_KEY="$(uuidgen)"

curl --request POST "$GRAPH_URL/match" \
  --header "x-api-key: $SIXTYFOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $MATCH_KEY" \
  --data '{"fields":{"email":"alex@example.com"},"limit":5}'
```

For example, a shared email can return one earlier record:

```json theme={null}
{
  "record": null,
  "items": [{
    "record_id": "application-42",
    "strength": "possibly_same",
    "labels": {"review_status": "reviewed"},
    "text_links": {},
    "evidence": [{
      "type": "identifier", "kind": "email", "value": "alex@example.com",
      "shared_by": 2, "network": null, "column": "email"
    }]
  }],
  "next_cursor": null,
  "charge_credits": 1
}
```

| Response field | Meaning |
| - | - |
| `record` | The supplied row's own record if its ID already exists, otherwise `null`. |
| `items` | Other matching records, strongest first. An empty array means the supplied fields produced no matches. |
| `items[].record_id`, `items[].labels` | The earlier row's ID and its recorded labels. |
| `items[].strength`, `items[].evidence` | The match classification and the identifiers, names, entities or text that support it. |
| `items[].text_links` | Counts by long-text column of other records with the same text, a copy or a shared template. |
| `next_cursor` | Always `null` for match. Set `limit` to request up to 100 results (default 10). |
| `charge_credits` | Credits charged for this request. A match can incur a charge even when the result is empty. |

A `same_person` match means both records point to the same person in the graph or multiple strong signals agree. A `possibly_same` match has one strong signal, such as a rare identifier or copied text. A `related` match can reflect a shared employer or document template. Read the evidence before using a match to make a decision.

For a retry of the same match, reuse the original body and `MATCH_KEY`. The API can replay the original result without charging again during the 24-hour idempotency window. Generate a fresh key for a new match.

## Look up a known record

Use the ID from your source row. URL-encode it as a single path segment.

| Method and path (relative to the graph) | Result |
| - | - |
| `GET /records/{record_id}` | Returns the record's labels, its subject and properties, attached nodes in `subject.connected`, other records in `linked`, and `charge_credits`. |
| `GET /records/{record_id}/connected` | Continues the attached-node list. Each item describes a node's kind, name, relation and direction. |
| `GET /records/{record_id}/linked` | Continues the list of related records with their match strength and evidence. |

The lookup includes up to 100 attached nodes and 20 linked records. Each list has its own `next_cursor`. Pass it as `cursor` to the corresponding endpoint until it returns `null`. See [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md#lattice-record-lookups) for lookup errors and [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md) for pricing.

## Labels

Label definitions belong to the graph. A label can take its value from a workflow column or accept writes through the API.

| Method and path (relative to the graph) | Request or result |
| - | - |
| `GET /labels` | Lists definitions, allowed values and the source column, if any. |
| `PUT /labels/{name}` | Defines or replaces a label. Send `values` and optionally `description` or `from_column`. |
| `POST /records/labels` | Sets up to 100 labels per call. Each item takes `record_id`, `label`, `value` and an optional `note`. |
| `GET /records/{record_id}/labels/history` | Lists changes newest first, including the source, who set the value and when. Pass `next_cursor` as `cursor` to continue. |

For example, define an API-managed label with `PUT /labels/review_status` and the body `{"values":["pending","reviewed"]}`. To set it on a record, send this body to `POST /records/labels`:

```json theme={null}
{
  "items": [
    {"record_id":"application-42","label":"review_status","value":"reviewed"}
  ]
}
```

Inspect both `applied` and `rejected`. A batch can contain both. Rejections identify an unknown label, a column-managed label, a disallowed value or a missing record. If the record is still being ingested, submit the rejected item as a new request after it becomes available. For a label managed by the workflow, set `from_column` when defining it and supply one of its allowed values in that column.

## Follow graph changes

`GET /lattice/graphs/{graph_id}/events` returns events oldest first. The first request starts at the graph's first event. The feed supports `record.added`, `record.linked` and `label.set`. When a new record links to an earlier one, `record_id` identifies the earlier record and `data.linked_record_id` identifies the new one. Setting a label can also emit `record.linked` for an existing connection. In that case, `data.linked_record_id` identifies the record whose label changed.

```bash theme={null}
curl --get "$GRAPH_URL/events" \
  --header "x-api-key: $SIXTYFOUR_API_KEY" \
  --data-urlencode "type=record.linked" \
  --data-urlencode "limit=50"
```

Repeat `type` to select multiple event types. For linked records, `linked_label` accepts a filter such as `review_status:reviewed`. The `limit` controls how many record additions and label writes the feed examines (default 20, maximum 50). Each can also emit its 20 strongest links, so a response can contain more events than the requested limit. Use the linked-records endpoint to explore additional links.

Save `next_cursor` after processing the page and send it as `since` on the next poll with the same filters. If `has_more` is true, fetch the next page immediately. Otherwise, retain the cursor for your next poll. Use `event_id` to deduplicate deliveries if your consumer retries. Events can take several minutes to appear.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.