Documents

The document register: statements, reports, agreements and other files filed on a client, an entity, an account or another record, with their labels and the period they are valid for. Reads need documents:read, writes documents:write and an operator seat. Every write takes ?dry_run=true and an Idempotency-Key header and is logged in the change history. A document from the legacy platform (origin: legacy) is read-only until your tenant has moved: a write is a 409 legacy_managed.

Data model

idstring: A UUID.
namestring or null: The file's display name.
kindstring or null: statement, kyc, aml, prospectus, fact_sheet, pack, poa, report, invoice, tax_document, trade_confirmation, audit_report or custom. A stored document can also be a contract, which the API does not set.
file_typestring: The legacy platform's file type: report, document, image, private-equity, transaction or invoice. Set through the API, else the legacy file's own (any spelling, an unknown value is document), else derived from kind (an image MIME type is image).
labelsarray of string: Labels set through the API, else the legacy file's tags.
ownerstring: aleta for a report Aleta generated, tenant otherwise. An Aleta report can only be relabelled, and only Aleta archives it.
target_kind, target_idstring or null: What the document is filed on: tenant, client, party, entity, custody_account, cash_account, holding, transaction, asset, tag, lens or ownership, and its id.
mime_type, byte_size, sha256string, integer, string or null: The file.
uploaded_attimestamp or null: RFC 3339, UTC.
valid_from, valid_todate or null: The period the document covers.
archived_at, archived_by, archive_reasontimestamp, string, string or null: Set once a DELETE archived the document.
originstring: legacy (mirrored from the legacy platform) or v1 (made on this platform, including the reports and exports Aleta generates).

GET/v1/documents

List documents

Returns the documents you can see, newest upload first, as a cursor list. An unknown parameter is a 400.

Query parameters

target_kind, target_idstring: Documents filed on this record.
kind, file_typestring: Documents of this kind or file type.
labelstring: Documents carrying this label.
include_archivedboolean: Also archived documents. Default false.
cursor, limitstring, integer: The page: limit defaults to 100, at most 1000.

Request

GET/v1/documents

curl -G https://api.aleta.ai/v1/documents \
  -H "Authorization: Bearer {access_token}" \
  -d target_kind=client -d target_id=019dfeb0-0511-77a7-a8be-a911ab988a0a

Response

{
  "data": [
    {
      "id": "019f95f0-2d40-7b58-8f6e-9a3c1d7e5b02",
      "name": "Q3 statement",
      "kind": "statement",
      "file_type": "document",
      "labels": ["board"],
      "owner": "tenant",
      "target_kind": "client",
      "target_id": "019dfeb0-0511-77a7-a8be-a911ab988a0a",
      "mime_type": "application/pdf",
      "byte_size": 182044,
      "sha256": "9f2c...",
      "uploaded_at": "2026-10-02T08:30:00Z",
      "valid_from": "2026-07-01",
      "valid_to": "2026-09-30",
      "archived_at": null,
      "archived_by": null,
      "archive_reason": null,
      "origin": "v1"
    }
  ],
  "next_cursor": null,
  "limit": 100
}

GET/v1/documents/{id}

Retrieve a document

Returns one document, an archived one too. An unknown id, one you cannot see, or one that is not a UUID is a 404.

Request

GET/v1/documents/{id}

curl https://api.aleta.ai/v1/documents/019f95f0-2d40-7b58-8f6e-9a3c1d7e5b02 \
  -H "Authorization: Bearer {access_token}"

PATCH/v1/documents/{id}

Update a document

Renames, retypes, relabels or re-dates a document; its target never moves. Send at least one field besides reason; unknown fields are a 400. labels: null clears the labels, an array replaces them; status: active brings back an archived document, status: archived is a 400; reason goes to the change history. Answers 200 with the document. A caller without an operator seat gets 403. Changing more than the labels of an Aleta report is a 409 in_use whose next_action is PATCH /v1/documents/{id} with field: labels.

Body parameters

name, kind, file_typestring: A file type sets the matching kind unless a kind is given.
labelsarray of string or null: At most 50, each at most 100 characters; trimmed, and a repeat (any case) is dropped.
valid_from, valid_todate or null: YYYY-MM-DD; valid_to not before valid_from.
statusstring: active.
reasonstring: For the change history.

Request

PATCH/v1/documents/{id}

curl -X PATCH https://api.aleta.ai/v1/documents/019f95f0-2d40-7b58-8f6e-9a3c1d7e5b02 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["board", "2026"]}'

DELETE/v1/documents/{id}

Delete a document

Archives the document; the file stays and PATCH with status: active brings it back. 204; an archived document answers 204 again. An Aleta report is a 409 in_use for anyone but Aleta; its next_action (ask_aleta) names the document. Optional ?reason= goes to the change history; it takes ?dry_run=true; any other query parameter is a 400.

Request

DELETE/v1/documents/{id}

curl -X DELETE https://api.aleta.ai/v1/documents/019f95f0-2d40-7b58-8f6e-9a3c1d7e5b02 \
  -H "Authorization: Bearer {access_token}"

Document extractions

Reading figures out of a document is not part of this release. The three extraction routes are reserved so that a call to them gets a clear answer rather than a 404: after the scope check (documents:read for the reads, documents:write for the create; 403 without it), each answers 501 not_implemented.

GET /v1/document-extractions: list extractions. Answers 501.
POST /v1/document-extractions: start an extraction. Takes ?dry_run=true and Idempotency-Key like every write, and answers 501.
GET /v1/document-extractions/{id}: retrieve one extraction. Answers 501.