HTTP API

Every path under /v1, with what it takes and answers, the operations of a changeset, and errors.

Everything Spool does is a call of this API. The command line, the studio and the MCP endpoint all call it. This page lists every path and shows the ones a pipeline uses.

Calling it

  • Address. spool dev listens on http://127.0.0.1:7765. Every path here is under /v1, except /healthz.
  • Who is calling. spool dev asks for nothing. spool serve wants Authorization: Bearer <token>, with a token from spool token add or the studio's Tokens page.
  • Bodies. JSON in, JSON out, on one line. No content-type header is needed for JSON. A field the server does not know is refused.
  • Waiting. A call that starts work answers at once with a run whose status is running. With wait_ms, in the body or the query, it waits that long for the run to finish first. GET /v1/runs/<run>?wait_ms=5000 waits for a run that was started before.
  • Lists. A list answers up to 100 entries, or limit up to 1,000, and next when there are more. Pass it back as after.
  • Errors. A refusal is {"error": {"code": "...", "message": "..."}} with a 4xx status. The message says what was wrong and names the thing.
  • Schema. spool schema prints the JSON Schema of every value on this page.

Every path

Method and pathWhat it does
GET /v1/infoThe entity types and their features, the sources and the extractors the project declares, counts, and the head of the log
POST /v1/loadLoads rows into a source
POST /v1/retractTakes back rows a source no longer holds
GET /v1/documents, POST /v1/documentsLists documents, stores documents
GET /v1/documents/{document}One document with its text
POST /v1/extractionsRuns an extractor over the documents it has not read
POST /v1/matchStarts a match
GET /v1/runsLists runs
GET /v1/runs/{run}One run and its report
GET /v1/runs/{run}/candidatesThe candidate pairs of a run that waits for judgements
POST /v1/runs/{run}/judgementsSends judgements for those pairs
POST /v1/runs/{run}/reconcileTurns a run's judgements into a changeset
POST /v1/runs/{run}/cancelCancels a run that waits for judgements
GET /v1/recordsRecords by entity_type, source, key, document, identity, words in q, or unassigned
GET /v1/records/{record}One record
POST /v1/records/identitiesThe identity of each of many records
GET /v1/identitiesIdentities by entity_type, words in q, or ids
GET /v1/identities/{identity}One identity and its records. An ID that was merged away answers with the identity that took its place
GET /v1/identities/{identity}/historyEvery changeset that touched it
POST /v1/identities/{identity}/splitSplits an identity
GET /v1/explain?a=&b=Why two records share an identity, or why they do not. Each is a record's ID, its source:key, or the name the lists give a record found in a document
GET /v1/changesets, POST /v1/changesetsReads the log, commits a changeset
POST /v1/changesets/{seq}/undoUndoes one changeset with a new one
POST /v1/idsMints identity IDs for create_identity
GET /v1/constraintsThe must_link and cannot_link constraints in force, by record or identity
GET /v1/review, GET /v1/review/{item}Review items by status, entity_type or record
GET /v1/review/{item}/caseOne item with everything needed to decide it
POST /v1/review/{item}/dismissCloses an item and leaves things as they are
GET /v1/drafts, GET /v1/drafts/{draft}Drafts
POST /v1/drafts/{draft}/approve, .../rejectCommits a draft, or closes it
GET /v1/people, POST /v1/people, POST /v1/people/{person}The accounts of people. Admins only
GET /v1/tokens, POST /v1/tokens, POST /v1/tokens/{token}/revokeTokens. Admins only
GET /healthz{"status":"ok"}, with no sign-in

Sign-in for browsers is under /auth, and the MCP endpoint is /mcp. MCP covers it.

The examples below start from an empty project:

spool init companies
cd companies
spool dev

Load rows

POST /v1/load takes rows as JSON objects, each with the columns the source declares:

curl -s -X POST http://127.0.0.1:7765/v1/load -d '{"source": "crm", "entity_type": "company", "wait_ms": 5000, "rows": [{"id": "c-1", "name": "Acorn Tools", "country": "GB"}, {"id": "c-2", "name": "ACORN TOOLS", "country": "GB"}, {"id": "c-5", "name": "Halden Group", "country": "GB"}, {"id": "c-6", "name": "Halden Group", "country": "US"}]}'
Output
{"run":{"run":1,"kind":"load","status":"succeeded","started_by":"user:01a1f0a3-7961-77eb-b436-a883824aafc0","entity_type":"company","strategy":null,"extractor":null,"started_at":"2026-11-18T21:50:07.715530Z","finished_at":"2026-11-18T21:50:07.726734Z","error":null,"load":{"run":1,"received":4,"inserted":4,"duplicates":0,"superseded":0,"restored":0,"returned":0,"committed":null,"possible_splits":0},"extraction":null,"resolution":null,"retraction":null}}

The answer is the load run. received is the rows sent, inserted the new records, duplicates the rows that were already held, and superseded the rows that are a new version of a row held before. Nothing is matched yet.

A CSV file goes as it is, with the source and the type in the query:

curl -s -X POST 'http://127.0.0.1:7765/v1/load?source=crm&entity_type=company&wait_ms=5000' -H 'content-type: text/csv' --data-binary @samples/crm-2.csv

Large loads go as an Arrow IPC stream in the body, with content-type: application/vnd.apache.arrow.stream and the same query. That is how the benchmarks load five million rows.

A row with a column the source does not declare, or without its key, is refused, and the whole call with it. A row under a key the server holds, with other values, becomes the next version of that row. With "replace": false in the body such a row is refused, and the whole call with it.

Runs

A match is a run. Start one for an entity type:

curl -s -X POST http://127.0.0.1:7765/v1/match -d '{"entity_type": "company", "wait_ms": 5000}'
Output
{"run":{"run":3,"kind":"match","status":"succeeded","started_by":"user:01a1f0a3-7961-77eb-b436-a883824aafc0","entity_type":"company","strategy":{"name":"rules","version":"0.1.0"},"extractor":null,"started_at":"2026-11-18T22:10:03.814727Z","finished_at":"2026-11-18T22:10:03.832263Z","error":null,"load":null,"extraction":null,"resolution":{"entity_type":"company","match_run":3,"reconcile_run":4,"new_records":7,"reexamined":0,"candidates":4,"judgements":{"match":3,"no_match":1,"unsure":0},"identities_created":5,"records_assigned":7,"versions_moved":0,"records_unassigned":0,"review":[],"committed":{"seq":1,"changeset":"01a1f0b5-b9b0-7443-a834-945d59293e96","content_hash":"32c29e26ae8c63c31300f3c95102c1c057f4eef72609815fd8f45d4dcc80fdd6"},"draft":null,"suggestions":null},"retraction":null}}
FieldMeaning
entity_typeThe type to match. Required
rematchtrue examines every record again by the rules as they are now. It suggests merges and makes none
commitfalse leaves the changeset as a draft to approve
strategy{"name": "..."}: a strategy of the project, or a name of your own for a run you judge yourself. Left out, the rules run
wait_msHow long to wait for it to finish

The run that answers is the match run. The reconcile run that turned its judgements into a changeset is the next one:

spool show runs
Output
run  kind       status     about           started by                                 started
4    reconcile  succeeded                  user:01a1f0a3-7961-77eb-b436-a883824aafc0  2026-11-18T21:50:07Z
3    match      succeeded  company, rules  user:01a1f0a3-7961-77eb-b436-a883824aafc0  2026-11-18T21:50:07Z
2    load       succeeded  company         user:01a1f0a3-7961-77eb-b436-a883824aafc0  2026-11-18T21:50:07Z
1    load       succeeded  company         user:01a1f0a3-7961-77eb-b436-a883824aafc0  2026-11-18T21:50:07Z

A run you judge yourself

A run with a strategy name the project does not have waits for judgements from the caller. This is how a matcher written in anything, running anywhere, takes part: Spool finds the candidate pairs, the caller judges them, and Spool applies the same four rules to the result as to its own.

curl -s -X POST http://127.0.0.1:7765/v1/load -d '{"source": "crm", "entity_type": "company", "wait_ms": 5000, "rows": [{"id": "c-10", "name": "Acorn Tooling", "country": "GB"}]}'
curl -s -X POST http://127.0.0.1:7765/v1/match -d '{"entity_type": "company", "strategy": {"name": "by-hand"}, "wait_ms": 5000}'
Output
{"run":{"run":6,"kind":"match","status":"open","started_by":"user:01a1f0a3-7961-77eb-b436-a883824aafc0","entity_type":"company","strategy":{"name":"by-hand","version":null},"extractor":null,"started_at":"2026-11-18T21:50:07.836922Z","finished_at":null,"error":null,"load":null,"extraction":null,"resolution":null,"retraction":null}}
RUN=$(spool show runs --kind match --limit 1 | awk 'NR==2 {print $1}')
curl -s -H 'accept: application/json' http://127.0.0.1:7765/v1/runs/$RUN/candidates
Output
{"candidates":[{"left_country":"GB","left_id":"34c3d52d-e53b-1559-7404-1892fb1fd4e3","left_name":"Acorn Tool","left_name_key":"acorn tool","right_country":"GB","right_id":"875986b9-a764-1450-33d1-2d4612fb4daa","right_name":"Acorn Tooling","right_name_key":"acorn tooling"},{"left_country":"GB","left_id":"875986b9-a764-1450-33d1-2d4612fb4daa","left_name":"Acorn Tooling","left_name_key":"acorn tooling","right_country":"GB","right_id":"a780fcfe-cb2f-21dd-25ea-11db898fd6a2","right_name":"ACORN TOOLS","right_name_key":"acorn tools"},{"left_country":"GB","left_id":"875986b9-a764-1450-33d1-2d4612fb4daa","left_name":"Acorn Tooling","left_name_key":"acorn tooling","right_country":"GB","right_id":"ab8e9d59-0aaa-96b9-ddb7-db0bff7a9356","right_name":"Acorn Tools","right_name_key":"acorn tools"}]}

Each candidate is a pair of records with the features of each. Without the accept header the candidates come as an Arrow IPC stream, which is what a matcher over many pairs wants. Judge them and reconcile:

LEFT=$(spool show records crm:c-10 | awk '/^record/ {print $2}')
RIGHT=$(spool show records crm:c-1 | awk '/^record/ {print $2}')
curl -s -X POST http://127.0.0.1:7765/v1/runs/$RUN/judgements -d '{"judgements": [{"left_id": "'$LEFT'", "right_id": "'$RIGHT'", "verdict": "match", "score": 0.97}]}'
curl -s -X POST http://127.0.0.1:7765/v1/runs/$RUN/reconcile -d '{}'
Output
{"entity_type":"company","match_run":6,"reconcile_run":7,"new_records":1,"reexamined":0,"candidates":3,"judgements":{"match":1,"no_match":0,"unsure":0},"identities_created":0,"records_assigned":1,"versions_moved":0,"records_unassigned":0,"review":[],"committed":{"seq":2,"changeset":"01a1f0b5-ba40-73bd-93b5-b29d667d9177","content_hash":"2166ed732fd26d3f68d52397ab5d896778167df0dab41e344bb652b16f20004b"},"draft":null,"suggestions":null}

verdict is match, no_match or unsure. A pair that gets no judgement is left undecided. score and detail are kept with the judgement and shown by spool explain.

Take rows back

curl -s -X POST http://127.0.0.1:7765/v1/retract -d '{"source": "crm", "entity_type": "company", "keys": ["c-6"], "reason": "deleted in the CRM", "wait_ms": 5000}'
Output
{"run":{"run":8,"kind":"retract","status":"succeeded","started_by":"user:01a1f0a3-7961-77eb-b436-a883824aafc0","entity_type":"company","strategy":null,"extractor":null,"started_at":"2026-11-18T21:55:21.428136Z","finished_at":"2026-11-18T21:55:21.435621Z","error":null,"load":null,"extraction":null,"resolution":null,"retraction":{"run":8,"received":1,"unknown":0,"retracted":1,"detached":1,"committed":{"seq":3,"changeset":"01a1f0a8-42d6-74a1-b108-f39ff16b5c91","content_hash":"a0a2fdd9d12ab55045afa04fe03e66aa8ebc5d68859201f76ba9741d722f0e2e"},"possible_splits":0}}}

The rows are taken back, not erased. Records and sources says what that means.

Documents and extraction

A document is a text, stored as it arrived. One goes as it is, with its source and key in the query:

curl -s -X POST 'http://127.0.0.1:7765/v1/documents?source=notes&key=notes-1.txt&wait_ms=5000' -H 'content-type: text/plain' --data-binary @samples/notes-1.txt

Several go as JSON:

curl -s -X POST http://127.0.0.1:7765/v1/documents -d '{"source": "notes", "wait_ms": 5000, "documents": [{"key": "notes-1.txt", "text": "Call with Dana Reyes on 12 November. She has moved to Acorn Tools Ltd and runs purchasing there."}]}'

POST /v1/extractions runs an extractor over the documents it has not read:

curl -s -X POST http://127.0.0.1:7765/v1/extractions -d '{"extractor": "companies", "wait_ms": 60000}'
Output
{"run":{"run":11,"kind":"extract","status":"succeeded","started_by":"user:01a1f0a3-7961-77eb-b436-a883824aafc0","entity_type":null,"strategy":null,"extractor":{"name":"companies","version":"eacb9397cacc366a1cd065d8f328039484a5e5d4fbf49b8ca1f2a3cbd34f8c92"},"started_at":"2026-11-18T21:55:21.478610Z","finished_at":"2026-11-18T21:55:22.855886Z","error":null,"load":null,"extraction":{"run":11,"documents":1,"mentions":1,"inserted":1,"duplicates":0,"superseded":0,"load_run":12},"resolution":null,"retraction":null}}
FieldMeaning
extractorThe extractor to run. May be left out when the project has one
sourceOnly the documents of this source
againtrue reads every document again
limitRead at most this many documents
wait_msHow long to wait for it to finish

What the extractor found are records, which the next match places. Extraction writes an extractor in each language.

Changesets

Every change to an identity is a changeset: one or more operations that are committed together or not at all, with an author and a reason. A match writes them, and so can any caller:

A=$(spool show records crm:c-5 | awk '/^record/ {print $2}')
B=$(spool show records crm:c-2 | awk '/^record/ {print $2}')
curl -s -X POST http://127.0.0.1:7765/v1/changesets -d '{"reason": "Halden Group is not Acorn Tools", "ops": [{"op": "constrain", "kind": "cannot_link", "a": "'$A'", "b": "'$B'"}]}'
Output
{"seq":4,"changeset":"01a1f0a4-ca2f-7368-b562-6231f33d6cab","content_hash":"6667f62333564c8f9cb31ccb0a4c421561e9f8fd8e576f13ed45209d87800777"}

seq is its position in the log.

OperationFieldsWhat it does
create_identityidentity, entity_typeMakes an identity with an ID from POST /v1/ids
assignrecord, from, toMoves a record. from is the identity it is in now, or null. to is where it goes, or null
mergefrom, intoMoves every record of from into into. from then answers with into
reinstateidentityMakes a merged identity current again. Used by undo
constrainkind, a, bmust_link or cannot_link between two records, which every later change must respect
unconstrainkind, a, bRemoves one

The body may carry base, the log position the caller last read. Each operation says what it expects to find, an assign its from for example, and a changeset whose expectations no longer hold is refused whole, with the operation that failed. So is one that would put two cannot_link records in one identity, or leave two must_link records apart.

A changeset that places the latest version of a row moves its earlier versions along. The server adds those moves to the changeset, so the log may show more operations than were sent. A match run counts them in versions_moved.

GET /v1/changesets?after=<seq> reads the log. Using the IDs shows a consumer following it.

Three calls write a changeset for you:

  • POST /v1/identities/{identity}/split with {"records": [...], "reason": "..."} makes a new identity, moves the named records into it, and adds a cannot_link between the sides unless keep_apart is false.
  • POST /v1/changesets/{seq}/undo with {"reason": "..."} commits the changeset that reverses one. With "commit": false it answers that changeset and commits nothing.
  • POST /v1/drafts/{draft}/approve commits a draft.

Identities runs each of them.

What a refusal looks like

curl -s -X POST http://127.0.0.1:7765/v1/match -d '{"entity_type": "person"}'
Output
{"error":{"code":"invalid","message":"entity type `person` is not declared; apply a manifest that declares it first"}}

What the API does not have

  • No stream and no webhook. A consumer polls the log.
  • No call that loads and matches in one step.
  • No bulk export.
  • Version v1 is the only version, and before 1.0 a release may change it. The changelog of each release will say so.