Documents

Stored files with their AI analysis: search, upload, download.

List and search documents#

GET/workspaces/{workspaceId}/documentsscope documents:readMCP list_documents

Newest first. With q, a text search over title, file name, notes, category and the AI analysis (summary, issuer, key content, tags); every word must match, accents and case don't matter. For questions in natural language use search or ask_butler.

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).

Query#

Field	Type	Description
`q`	string	Words to find, e.g. "stadtwerke 2026".
`category`	`invoice` \	`contract` \	`insurance` \	`bank` \	`tax` \	`payslip` \	`medical` \	`school` \	`authority` \	`warranty` \	`receipt` \	`letter` \	`other`
`limit`	integer	Maximum number of results (1–100, default 25). Default: `25`.
`cursor`	string	Cursor from nextCursor of the previous page.

Request#

Shell

curl "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"

Response `200`#

Field	Type	Description
`data`	array of Document
`data[].id`	string
`data[].title`	string
`data[].category`	string	invoice, contract, insurance, bank, tax, payslip, medical, school, authority, warranty, receipt, letter, other
`data[].fileName`	string
`data[].mimeType`	string
`data[].size`	integer	Bytes.
`data[].documentDate`	string or null	YYYY-MM-DD: set by hand, else read by the AI.
`data[].notes`	string
`data[].sha256`	string or null
`data[].createdBy`	string or null
`data[].createdAt`	string or null
`data[].analysis`	DocumentAnalysis
`data[].analysis.status`	string	none, pending, done, error, refused, unsupported, tooLarge, off, noCredits or quotaExceeded.
`data[].analysis.summary`	string or null
`data[].analysis.issuer`	string or null
`data[].analysis.result`	object or null	Full AI result: payment (payee, amount, IBAN, due date), contract, deadlines, events, tasks, tags.
`nextCursor`	string or null	Pass as cursor to get the next page; null on the last page.

JSON

{
  "data": [
    {
      "id": "Ab3Cd5Ef7G",
      "title": "Elternabend 3b",
      "category": "string",
      "fileName": "rechnung.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "documentDate": "2026-11-20",
      "notes": "",
      "sha256": "string",
      "createdBy": "string",
      "createdAt": "2026-11-20T19:30:00+01:00",
      "analysis": {
        "status": "string",
        "summary": "string",
        "issuer": "string",
        "result": {}
      }
    }
  ],
  "nextCursor": "string"
}

Upload a document#

POST/workspaces/{workspaceId}/documentsscope documents:writeMCP upload_document

Send the file as the raw request body with its Content-Type (PDF, JPEG, PNG, WebP, GIF, HEIC; max 25 MB) and the file name in the query. Like an upload in the app: a duplicate (same content) answers 409 with its id, the file counts towards the owner's storage, and – if the workspace has AI on and your document setting is automatic – it is analysed right away (1 credit per page).

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).

Query#

Field	Type	Description
`fileName` (required)	string	File name incl. extension, e.g. "rechnung.pdf".
`title`	string	Title (default: the file name without extension).

Body#

The file's bytes; Content-Type: application/pdf, image/jpeg, image/png, image/webp, image/gif or image/heic.

Request#

Shell

curl -X POST "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents?fileName=rechnung.pdf" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @rechnung.pdf

Response `201`#

Field	Type	Description
`id`	string
`title`	string
`category`	string	invoice, contract, insurance, bank, tax, payslip, medical, school, authority, warranty, receipt, letter, other
`fileName`	string
`mimeType`	string
`size`	integer	Bytes.
`documentDate`	string or null	YYYY-MM-DD: set by hand, else read by the AI.
`notes`	string
`sha256`	string or null
`createdBy`	string or null
`createdAt`	string or null
`analysis`	DocumentAnalysis
`analysis.status`	string	none, pending, done, error, refused, unsupported, tooLarge, off, noCredits or quotaExceeded.
`analysis.summary`	string or null
`analysis.issuer`	string or null
`analysis.result`	object or null	Full AI result: payment (payee, amount, IBAN, due date), contract, deadlines, events, tasks, tags.

JSON

{
  "id": "Ab3Cd5Ef7G",
  "title": "Elternabend 3b",
  "category": "string",
  "fileName": "rechnung.pdf",
  "mimeType": "application/pdf",
  "size": 184320,
  "documentDate": "2026-11-20",
  "notes": "",
  "sha256": "string",
  "createdBy": "string",
  "createdAt": "2026-11-20T19:30:00+01:00",
  "analysis": {
    "status": "string",
    "summary": "string",
    "issuer": "string",
    "result": {}
  }
}

Get a document#

GET/workspaces/{workspaceId}/documents/{documentId}scope documents:readMCP get_document

Metadata and the AI analysis (summary, issuer, payment, deadlines, …). The file itself: download_document.

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).
`documentId`	string

Request#

Shell

curl "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents/Dc5Yh1Pt8Q" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"

Response `200`#

Field	Type	Description
`id`	string
`title`	string
`category`	string	invoice, contract, insurance, bank, tax, payslip, medical, school, authority, warranty, receipt, letter, other
`fileName`	string
`mimeType`	string
`size`	integer	Bytes.
`documentDate`	string or null	YYYY-MM-DD: set by hand, else read by the AI.
`notes`	string
`sha256`	string or null
`createdBy`	string or null
`createdAt`	string or null
`analysis`	DocumentAnalysis
`analysis.status`	string	none, pending, done, error, refused, unsupported, tooLarge, off, noCredits or quotaExceeded.
`analysis.summary`	string or null
`analysis.issuer`	string or null
`analysis.result`	object or null	Full AI result: payment (payee, amount, IBAN, due date), contract, deadlines, events, tasks, tags.

JSON

{
  "id": "Ab3Cd5Ef7G",
  "title": "Elternabend 3b",
  "category": "string",
  "fileName": "rechnung.pdf",
  "mimeType": "application/pdf",
  "size": 184320,
  "documentDate": "2026-11-20",
  "notes": "",
  "sha256": "string",
  "createdBy": "string",
  "createdAt": "2026-11-20T19:30:00+01:00",
  "analysis": {
    "status": "string",
    "summary": "string",
    "issuer": "string",
    "result": {}
  }
}

Change a document#

PATCH/workspaces/{workspaceId}/documents/{documentId}scope documents:writeMCP update_document

Title, category, notes or date. What you set here is kept even if the AI analyses the document again.

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).
`documentId`	string

Body#

Field	Type	Description
`title`	string
`category`	`invoice` \	`contract` \	`insurance` \	`bank` \	`tax` \	`payslip` \	`medical` \	`school` \	`authority` \	`warranty` \	`receipt` \	`letter` \	`other`
`notes`	string
`documentDate`	string or null	YYYY-MM-DD; null goes back to the AI's date.

Request#

Shell

curl -X PATCH "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents/Dc5Yh1Pt8Q" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Elternabend 3b"}'

Response `200`#

Field	Type	Description
`id`	string
`title`	string
`category`	string	invoice, contract, insurance, bank, tax, payslip, medical, school, authority, warranty, receipt, letter, other
`fileName`	string
`mimeType`	string
`size`	integer	Bytes.
`documentDate`	string or null	YYYY-MM-DD: set by hand, else read by the AI.
`notes`	string
`sha256`	string or null
`createdBy`	string or null
`createdAt`	string or null
`analysis`	DocumentAnalysis
`analysis.status`	string	none, pending, done, error, refused, unsupported, tooLarge, off, noCredits or quotaExceeded.
`analysis.summary`	string or null
`analysis.issuer`	string or null
`analysis.result`	object or null	Full AI result: payment (payee, amount, IBAN, due date), contract, deadlines, events, tasks, tags.

JSON

{
  "id": "Ab3Cd5Ef7G",
  "title": "Elternabend 3b",
  "category": "string",
  "fileName": "rechnung.pdf",
  "mimeType": "application/pdf",
  "size": 184320,
  "documentDate": "2026-11-20",
  "notes": "",
  "sha256": "string",
  "createdBy": "string",
  "createdAt": "2026-11-20T19:30:00+01:00",
  "analysis": {
    "status": "string",
    "summary": "string",
    "issuer": "string",
    "result": {}
  }
}

Delete a document#

DELETE/workspaces/{workspaceId}/documents/{documentId}scope documents:writeMCP delete_document

Deletes the document and its file for everyone.

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).
`documentId`	string

Request#

Shell

curl -X DELETE "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents/Dc5Yh1Pt8Q" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"

Response `200`#

Field	Type	Description
`id`	string
`deleted`	`true`

JSON

{
  "id": "Ab3Cd5Ef7G",
  "deleted": false
}

Download the file#

GET/workspaces/{workspaceId}/documents/{documentId}/filescope documents:read

The original file (PDF or image) with its Content-Type and file name.

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).
`documentId`	string

Request#

Shell

curl "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents/Dc5Yh1Pt8Q/file" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"

Response `200`#

The file itself, with Content-Type and Content-Disposition (file name).

Analyse a document with AI#

POST/workspaces/{workspaceId}/documents/{documentId}/analyzescope documents:writeMCP analyze_document

Starts the AI analysis (1 credit per page, paid by the workspace owner). It runs in the background: poll get_document until analysis.status is no longer pending. Needs AI turned on for the workspace.

Path#

Field	Type	Description
`workspaceId`	string	Workspace id (from list_workspaces).
`documentId`	string

Body#

Field	Type	Description
`again`	boolean	Analyse a document that was already analysed once more (costs credits again). Default: `false`.

Request#

Shell

curl -X POST "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/documents/Dc5Yh1Pt8Q/analyze" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"again": false}'

Response `202`#

Field	Type	Description
`id`	string
`title`	string
`category`	string	invoice, contract, insurance, bank, tax, payslip, medical, school, authority, warranty, receipt, letter, other
`fileName`	string
`mimeType`	string
`size`	integer	Bytes.
`documentDate`	string or null	YYYY-MM-DD: set by hand, else read by the AI.
`notes`	string
`sha256`	string or null
`createdBy`	string or null
`createdAt`	string or null
`analysis`	DocumentAnalysis
`analysis.status`	string	none, pending, done, error, refused, unsupported, tooLarge, off, noCredits or quotaExceeded.
`analysis.summary`	string or null
`analysis.issuer`	string or null
`analysis.result`	object or null	Full AI result: payment (payee, amount, IBAN, due date), contract, deadlines, events, tasks, tags.

JSON

{
  "id": "Ab3Cd5Ef7G",
  "title": "Elternabend 3b",
  "category": "string",
  "fileName": "rechnung.pdf",
  "mimeType": "application/pdf",
  "size": 184320,
  "documentDate": "2026-11-20",
  "notes": "",
  "sha256": "string",
  "createdBy": "string",
  "createdAt": "2026-11-20T19:30:00+01:00",
  "analysis": {
    "status": "string",
    "summary": "string",
    "issuer": "string",
    "result": {}
  }
}

Documents

List and search documents#

Path#

Query#

Request#

Response 200#

Upload a document#

Path#

Query#

Body#

Request#

Response 201#

Get a document#

Path#

Request#

Response 200#

Change a document#

Path#

Body#

Request#

Response 200#

Delete a document#

Path#

Request#

Response 200#

Download the file#

Path#

Request#

Response 200#

Analyse a document with AI#

Path#

Body#

Request#

Response 202#

Response `200`#

Response `201`#

Response `200`#

Response `200`#

Response `200`#

Response `200`#

Response `202`#