DevelopersYour tokens
Reference

Documents

What is on file: listed, searched, opened with a window of its words, added, filed as something else, moved, linked to people and things, shared out. A change needs the write scope; adding one needs the role and the scope but not the plan.

GETSearch/searchGETThe documents/documentsPOSTA document in/documentsGETOne document/documents/{document}PATCHCorrect a document/documents/{document}GETThe file itself/documents/{document}/files/{file}GETOne page as a picture/documents/{document}/files/{file}/pages/{page}POSTSave a note as a document/documents/notePOSTFile a document as something else/documents/{document}/typePOSTLink a person or thing/documents/{document}/entitiesDELETEUnlink a person or thing/documents/{document}/entities/{entity}POSTLooks right/documents/{document}/reviewedPOSTRead it again/documents/{document}/read-againPOSTShare a document by link/documents/{document}/linksDELETETake a link back/documents/{document}/links/{link}
#
GETapi.thawed.app/v1/search
Scope: read · every token has it

The Library's search - words, meaning, an identifier typed in, and the people & things by name, fused - with the Library's filters on top. An identifier that matched is named in matched_on; the number itself comes back only with the identifiers scope.

Query
qstringqueryrequired
categorystringquery
A category's slug or name.
typestringquery
A type's slug or name.
person_or_thingstringquery
A person or thing's id or name.
yearintegerquery
The year on the document.
include_supersededbooleanquery
Include documents replaced by a newer version.
meaningbooleanquery
Search by meaning as well as by words. Off is faster.
limitintegerquery
Responses
200
The documents found, best first, and the people & things whose names matched.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
422
A field was wrong. errors names each one.
Problem
200 answer
resultsarray of any
totalinteger
people_and_thingsarray of Named
library_urlstring
Request
curl "https://api.thawed.app/v1/search?q=electric+bill" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
{
  "results": [
    {
      "id": "019958a0-2d5f-7e4b-8c30-4a1d3b7f9e22",
      "title": "Bluebonnet Electric bill September 2026",
      "type": "utilities/electric-bill",
      "category": "home",
      "date": "2026-09-12",
      "period": {
        "from": "marisol@example.com",
        "to": "billing@bluebonnet.example"
      },
      "status": "filed",
      "needs_look": false,
      "read": "full",
      "superseded": false,
      "duplicate": false,
      "people_and_things": [
        {
          "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
          "title": "Bluebonnet Electric bill September 2026",
          "name": "Marisol Alvarez",
          "kind": "document",
          "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
          "role": "subject"
        }
      ],
      "arrived": "2026-09-12",
      "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
      "snippet": "…amount due $129.50 by October 1, 2026. Your account is enrolled in AutoPay…",
      "matched_on": "words"
    }
  ],
  "total": 412,
  "people_and_things": [
    {
      "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
      "title": "Bluebonnet Electric bill September 2026",
      "name": "Marisol Alvarez",
      "kind": "document",
      "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
    }
  ],
  "library_url": "https://go.thawed.app/library?type=utilities%2Felectric-bill"
}
#

The documents

GETapi.thawed.app/v1/documents
Scope: read · every token has itPaged

The Library's filters, newest first by the date on the document (the first known of the printed date, the period, the day it was had before Thaw, the arrival) or by arrival. Pages by cursor; a cursor stays right when documents arrive between pages.

Query
categorystringquery
A category's slug or name.
typestringquery
A type's slug or name.
person_or_thingstringquery
A person or thing's id or name.
yearintegerquery
The year on the document.
sincestring (date)query
Arrived on or after this day.
needs_lookbooleanquery
Only the ones waiting on a person.
shredbooleanquery
Only the ones past their keep-until date.
include_supersededbooleanquery
Include documents replaced by a newer version.
sortstringquery
datearrival
limitintegerquery
cursorstringquery
The next_cursor of the page before.
Responses
200
One page of documents.
400
The request could not be read (a cursor that is not one, for instance).
Problem
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
422
A field was wrong. errors names each one.
Problem
200 answer
documentsarray of DocumentRow
totalinteger
How many match the filters altogether.
next_cursorstring or null
Request
curl "https://api.thawed.app/v1/documents" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
{
  "documents": [
    {
      "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
      "title": "Bluebonnet Electric bill September 2026",
      "type": "utilities/electric-bill",
      "category": "home",
      "date": "2026-09-12",
      "period": {
        "from": "marisol@example.com",
        "to": "billing@bluebonnet.example"
      },
      "status": "filed",
      "needs_look": false,
      "read": "full",
      "superseded": false,
      "duplicate": false,
      "people_and_things": [
        {
          "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
          "title": "Bluebonnet Electric bill September 2026",
          "name": "Marisol Alvarez",
          "kind": "document",
          "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
          "role": "subject"
        }
      ],
      "arrived": "2026-09-12",
      "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
    }
  ],
  "total": 412,
  "next_cursor": "eyJkIjoiMjAyNi0wOS0xMiIsImlkIjoi…"
}
#

A document in

POSTapi.thawed.app/v1/documents
Scope: write · put documents in, on every planTakes Idempotency-Key

One file as file, or photographs of pages as pages[], assembled into one PDF the way the scan page assembles them (separate makes one document per page; one page alone is one document). In a business, for=receipt tells Thaw what it is looking at, and several pages are always one receipt. Read in full, live. Refused with 403 when the plan has no room. Sent as multipart form data.

Headers
Idempotency-Keystringheader
Any string of the caller's choosing. The same key with the same body within a day replays the first answer, marked Idempotent-Replayed: true; with a different body it is 422; while the first call is still running it is 409.
Bodymultipart/form-data
filestring (binary)
pagesarray of string (binary)
JPEG, PNG, WebP, HEIC or PDF, one per page.
titlestring
separateboolean
forstring
receipt
Responses
201
Received. Thaw is reading it.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
422
A field was wrong. errors names each one.
Problem
201 answer
documentsarray of DocumentRow
messagestring
Request
curl -X POST "https://api.thawed.app/v1/documents" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@scan.pdf" \
  -F "pages[]=@page-1.jpg" \
  -F "title=Bluebonnet Electric bill September 2026" \
  -F "separate=true" \
  -F "for=receipt"
Response 201
{
  "documents": [
    {
      "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
      "title": "Bluebonnet Electric bill September 2026",
      "type": "utilities/electric-bill",
      "category": "home",
      "date": "2026-09-12",
      "period": {
        "from": "marisol@example.com",
        "to": "billing@bluebonnet.example"
      },
      "status": "filed",
      "needs_look": false,
      "read": "full",
      "superseded": false,
      "duplicate": false,
      "people_and_things": [
        {
          "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
          "title": "Bluebonnet Electric bill September 2026",
          "name": "Marisol Alvarez",
          "kind": "document",
          "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
          "role": "subject"
        }
      ],
      "arrived": "2026-09-12",
      "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
    }
  ],
  "message": "Received. Thaw is reading it."
}
#

One document

GETapi.thawed.app/v1/documents/{document}
Scope: read · every token has it

The document in full - the row, the summary, the facts, what is due, what it replaced, the links out - and, with text=1, a window of its words by page. Asking for the words is a view of the document and is written to the audit log as one.

Path
documentstring (uuid)pathrequired
Query
textbooleanquery
pageintegerquery
The page the window starts on.
max_charsintegerquery
Responses
200
The document.
Document
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
404
Nothing of that id in this family or business.
Problem
Request
curl "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
{
  "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
  "title": "Bluebonnet Electric bill September 2026",
  "text": "When does the electric bill come due?",
  "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
  "metadata": {
    "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "summary": "The September bill: $129.50, due 1 October, paid by autopay.",
    "confidence": 92,
    "page_count": 3,
    "read_by_ocr_pages": 1,
    "retention_until": "2026-10-01",
    "corrected_by_hand": [
      "string"
    ],
    "arrived_by": "email",
    "facts": [
      {
        "id": "019958a0-4f71-706d-8e52-6c3f5d91b044",
        "key": "staging/019958a0-2d5f…/scan.pdf",
        "label": "Amount due",
        "role": "money",
        "value": "$129.50",
        "number": 129.5,
        "date": "2026-09-12",
        "currency": "USD",
        "page": 1,
        "corrected_by_hand": false
      }
    ],
    "identifiers_shown": false,
    "up_next": [
      {
        "id": "019958a0-2d5f-7e4b-8c30-4a1d3b7f9e22",
        "kind": "document",
        "kind_label": "Person",
        "title": "Bluebonnet Electric bill September 2026",
        "due": "2026-10-01",
        "status": "filed",
        "snoozed_until": "2026-10-01",
        "amount": 129.5,
        "currency": "USD",
        "if_missed": "A late fee of $10 and a possible disconnection notice.",
        "what_to_do": {
          "summary": "The September bill: $129.50, due 1 October, paid by autopay.",
          "steps": [
            "string"
          ],
          "phone": "+1 512 555 0142",
          "links": [
            "string"
          ],
          "prepared": "2026"
        },
        "document": {
          "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
          "title": "Bluebonnet Electric bill September 2026",
          "name": "scan.pdf",
          "kind": "document",
          "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
        },
        "person_or_thing": {
          "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
          "title": "Bluebonnet Electric bill September 2026",
          "name": "Marisol Alvarez",
          "kind": "person",
          "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
        },
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
      }
    ],
    "replaces": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
      }
    ],
    "replaced_by": {
      "id": "019958a0-2d5f-7e4b-8c30-4a1d3b7f9e22",
      "title": "Bluebonnet Electric bill September 2026",
      "name": "Marisol Alvarez",
      "kind": "document",
      "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
    },
    "duplicate_of": {
      "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
      "title": "Bluebonnet Electric bill September 2026",
      "name": "Marisol Alvarez",
      "kind": "document",
      "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
    },
    "links_out": [
      {}
    ],
    "text_window": {
      "from_page": 1,
      "to_page": 1,
      "total_pages": 3,
      "more": false,
      "next_page": 1
    }
  }
}
#

Correct a document

PATCHapi.thawed.app/v1/documents/{document}
Scope: write · change things, on a paid planTakes Idempotency-Key

The review loop - title, summary, the date printed on it, the type (by id, slug or name, or null to clear it) and the category. Whatever is corrected is the person's from then on, and a later re-read never touches it. At least one field.

Path
documentstring (uuid)pathrequired
Headers
Idempotency-Keystringheader
Any string of the caller's choosing. The same key with the same body within a day replays the first answer, marked Idempotent-Replayed: true; with a different body it is 422; while the first call is still running it is 409.
BodyJSON
titlestring
summarystring or null
doc_datestring (date) or null
typestring or null
category_idstring (uuid) or null
Responses
200
The document, and which fields changed.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
422
A field was wrong. errors names each one.
Problem
200 answer
documentDocumentRow
One document as a list shows it.
editedarray of string
Request
curl -X PATCH "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bluebonnet Electric bill September 2026","summary":"The September bill: $129.50, due 1 October, paid by autopay.","doc_date":"2026-09-12","type":"utilities/electric-bill","category_id":"019958a0-4f71-706d-8e52-6c3f5d91b044"}'
Body
{
  "title": "Bluebonnet Electric bill September 2026",
  "summary": "The September bill: $129.50, due 1 October, paid by autopay.",
  "doc_date": "2026-09-12",
  "type": "utilities/electric-bill",
  "category_id": "019958a0-4f71-706d-8e52-6c3f5d91b044"
}
Response 200
{
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  },
  "edited": [
    "string"
  ]
}
#

The file itself

GETapi.thawed.app/v1/documents/{document}/files/{file}
Scope: files · the original file and the pages

Streamed as the web streams it, decrypted on the way out. Needs the files scope. Never a quarantined file. download=1 sends it as an attachment.

Path
documentstring (uuid)pathrequired
filestring (uuid)pathrequired
One of the document's files, from files on the document.
Query
downloadbooleanquery
Responses
200
The file, with its own content type.
*/*
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
410
A refusal, as a problem.
Problem
Request
curl "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/files/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
*/*
#

One page as a picture

GETapi.thawed.app/v1/documents/{document}/files/{file}/pages/{page}
Scope: files · the original file and the pages

A PDF's page drawn as a PNG, as the phone shows it. Needs the files scope. Up to 2200 px on the long edge.

Path
documentstring (uuid)pathrequired
filestring (uuid)pathrequired
One of the document's files, from files on the document.
pageintegerpathrequired
Query
wintegerquery
The long edge in pixels.
Responses
200
The page.
image/png
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
Request
curl "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/files/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/pages/PAGE" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
image/png
#

Save a note as a document

POSTapi.thawed.app/v1/documents/note
Scope: write · put documents in, on every planTakes Idempotency-Key

Words become a page, filed and read like anything else - what the MCP save_note tool does. person_or_thing (an id or a name) links it; date is the day it is about, today if none.

Headers
Idempotency-Keystringheader
Any string of the caller's choosing. The same key with the same body within a day replays the first answer, marked Idempotent-Replayed: true; with a different body it is 422; while the first call is still running it is 409.
BodyJSON
titlestringrequired
textstringrequired
person_or_thingstring
datestring (date)
Responses
201
The document.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
422
A field was wrong. errors names each one.
Problem
201 answer
documentDocumentRow
One document as a list shows it.
Request
curl -X POST "https://api.thawed.app/v1/documents/note" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bluebonnet Electric bill September 2026","text":"When does the electric bill come due?","person_or_thing":"Marisol Alvarez","date":"2026-09-12"}'
Body
{
  "title": "Bluebonnet Electric bill September 2026",
  "text": "When does the electric bill come due?",
  "person_or_thing": "Marisol Alvarez",
  "date": "2026-09-12"
}
Response 201
{
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  }
}
#

File a document as something else

POSTapi.thawed.app/v1/documents/{document}/type
Scope: write · change things, on a paid planTakes Idempotency-Key

An existing type by type_id, or a new one of the family's own by name and category_id. move_all also moves everything filed as the type this document carries now, which is how a household merges two of its own types.

Path
documentstring (uuid)pathrequired
Headers
Idempotency-Keystringheader
Any string of the caller's choosing. The same key with the same body within a day replays the first answer, marked Idempotent-Replayed: true; with a different body it is 422; while the first call is still running it is 409.
BodyJSON
type_idstring (uuid)
namestring
category_idstring (uuid)
move_allboolean
Responses
200
The document, the type it carries now, and how many others moved with it.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
422
A field was wrong. errors names each one.
Problem
200 answer
documentDocumentRow
One document as a list shows it.
typeNamed
movedinteger
Request
curl -X POST "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/type" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type_id":"019958a0-4f71-706d-8e52-6c3f5d91b044","name":"Marisol Alvarez","category_id":"019958a0-4f71-706d-8e52-6c3f5d91b044","move_all":false}'
Body
{
  "type_id": "019958a0-4f71-706d-8e52-6c3f5d91b044",
  "name": "Marisol Alvarez",
  "category_id": "019958a0-4f71-706d-8e52-6c3f5d91b044",
  "move_all": false
}
Response 200
{
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  },
  "type": {
    "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
    "title": "Bluebonnet Electric bill September 2026",
    "name": "Electric bill",
    "kind": "document",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  },
  "moved": 3
}
#

Link a person or thing

POSTapi.thawed.app/v1/documents/{document}/entities
Scope: write · change things, on a paid planTakes Idempotency-Key

One already on file by entity_id, or a new one by name and kind. role is what the document is to them - subject unless said otherwise.

Path
documentstring (uuid)pathrequired
Headers
Idempotency-Keystringheader
Any string of the caller's choosing. The same key with the same body within a day replays the first answer, marked Idempotent-Replayed: true; with a different body it is 422; while the first call is still running it is 409.
BodyJSON
entity_idstring (uuid)
namestring
kindstring
personpetorganizationpropertyvehiclefinancial_accountpolicyasset
rolestring
subjectissuerpayerpayeeownercovered
Responses
200
The person or thing, and the document.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
422
A field was wrong. errors names each one.
Problem
200 answer
person_or_thingPersonOrThing
documentDocumentRow
One document as a list shows it.
Request
curl -X POST "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/entities" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"019958a0-3e60-7f5c-9d41-5b2e4c80af33","name":"Marisol Alvarez","kind":"person","role":"subject"}'
Body
{
  "entity_id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
  "name": "Marisol Alvarez",
  "kind": "person",
  "role": "subject"
}
Response 200
{
  "person_or_thing": {
    "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
    "name": "Marisol Alvarez",
    "kind": "person",
    "kind_label": "Person",
    "subtitle": "Due 1 October · $129.50",
    "also_known_as": [
      "string"
    ],
    "details": {},
    "gone": "2025-06-30",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  },
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  }
}
#

Unlink a person or thing

DELETEapi.thawed.app/v1/documents/{document}/entities/{entity}
Scope: write · change things, on a paid plan

Take a person or thing off a document. The link goes, the document and the person stay; a person left on no document at all is tidied away by the next recompute.

Path
documentstring (uuid)pathrequired
entitystring (uuid)pathrequired
A person or thing's id.
Responses
200
The document.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
200 answer
documentDocumentRow
One document as a list shows it.
Request
curl -X DELETE "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/entities/019958a0-3e60-7f5c-9d41-5b2e4c80af33" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
{
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  }
}
#

Looks right

POSTapi.thawed.app/v1/documents/{document}/reviewed
Scope: write · change things, on a paid plan

A document waiting on a look is filed as it stands.

Path
documentstring (uuid)pathrequired
Responses
200
The document.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
200 answer
documentDocumentRow
One document as a list shows it.
Request
curl -X POST "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/reviewed" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
{
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  }
}
#

Read it again

POSTapi.thawed.app/v1/documents/{document}/read-again
Scope: write · change things, on a paid plan

A fresh read in full, live. A file that failed the virus scan stays closed.

Path
documentstring (uuid)pathrequired
Responses
202
Reading. The document, as it stands before the read.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
202 answer
documentDocumentRow
One document as a list shows it.
Request
curl -X POST "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/read-again" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 202
{
  "document": {
    "id": "019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
    "title": "Bluebonnet Electric bill September 2026",
    "type": "utilities/electric-bill",
    "category": "home",
    "date": "2026-09-12",
    "period": {
      "from": "marisol@example.com",
      "to": "billing@bluebonnet.example"
    },
    "status": "filed",
    "needs_look": false,
    "read": "full",
    "superseded": false,
    "duplicate": false,
    "people_and_things": [
      {
        "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
        "title": "Bluebonnet Electric bill September 2026",
        "name": "Marisol Alvarez",
        "kind": "document",
        "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
        "role": "subject"
      }
    ],
    "arrived": "2026-09-12",
    "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11"
  }
}
#

Share a document by link

POSTapi.thawed.app/v1/documents/{document}/links
Scope: write · change things, on a paid planTakes Idempotency-Key

A link anyone holding can open, with a life in days, a passcode if wanted and a view limit. The URL is in this answer and nowhere else.

Path
documentstring (uuid)pathrequired
Headers
Idempotency-Keystringheader
Any string of the caller's choosing. The same key with the same body within a day replays the first answer, marked Idempotent-Replayed: true; with a different body it is 422; while the first call is still running it is 409.
BodyJSON
daysintegerrequired
passcodestring
max_viewsinteger
Responses
201
The link.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
422
A field was wrong. errors names each one.
Problem
201 answer
urlstring
linkShareLink
A link out, without its token.
Request
curl -X POST "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/links" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"days":14,"passcode":"4821","max_views":5}'
Body
{
  "days": 14,
  "passcode": "4821",
  "max_views": 5
}
Response 201
{
  "url": "https://go.thawed.app/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11",
  "link": {
    "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
    "expires": "2026-10-01",
    "views": 2,
    "max_views": 5,
    "passcode": false,
    "live": false,
    "revoked": false
  }
}
#
DELETEapi.thawed.app/v1/documents/{document}/links/{link}
Scope: write · change things, on a paid plan

End a share link. Whoever holds the address sees nothing from then on; the audit row says who ended it.

Path
documentstring (uuid)pathrequired
linkstring (uuid)pathrequired
Responses
200
The link, ended.
401
No token, a token that has ended, or one issued for the other door. WWW-Authenticate names the resource metadata document.
Problem
403
The token, the role or the plan does not allow it. A missing scope is named in scope and in the WWW-Authenticate header as insufficient_scope; a plan that does not come with it says which one does.
Problem
404
Nothing of that id in this family or business.
Problem
200 answer
linkShareLink
A link out, without its token.
Request
curl -X DELETE "https://api.thawed.app/v1/documents/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11/links/019958a0-1c4e-7d3a-9b2f-3f0c2a6e8d11" \
  -H "Authorization: Bearer $THAW_TOKEN"
Response 200
{
  "link": {
    "id": "019958a0-3e60-7f5c-9d41-5b2e4c80af33",
    "expires": "2026-10-01",
    "views": 2,
    "max_views": 5,
    "passcode": false,
    "live": false,
    "revoked": false
  }
}