---
title: "File a new document"
method: POST
path: "/api/v1/documents"
tags: ["Files"]
---

# File a new document

`POST /api/v1/documents`

## Request

- Base URL: `http://localhost:5180`
- URL: `http://localhost:5180/api/v1/documents`
- Auth: API key in cookie `better-auth.session_token`

Files the document’s record, linked to the lease, unit, building or contact it is about. Its bytes follow in two calls: POST `/documents/{id}/content` with the size and SHA-256, then PUT the file to the same address. The links decide which region the bytes are stored in, so they are set here, before any bytes exist.

## Request body

- object
  - `name` string, required
  - `kind` 'lease' | 'lease_annex' | 'inspection_report' | 'invoice' | 'receipt' | 'quote' | 'supplier_invoice' | 'certificate' | 'id_document' | 'proof_of_income' | 'insurance_policy' | 'deed' | 'floor_plan' | 'photo' | 'correspondence' | 'formal_notice' | 'statement' | 'tax_document' | 'lease_termination' | 'lease_amendment' | 'other'
  - `contentType` string, required
  - `size` integer, required
  - `leaseId` string: Stable record id, e.g. `lse_012`.
  - `unitId` string: Stable record id, e.g. `lse_012`.
  - `buildingId` string: Stable record id, e.g. `lse_012`.
  - `contactId` string: Stable record id, e.g. `lse_012`.

## Response `200`

Filed, waiting for its bytes.

- object
  - `ok` unknown, required
  - `data` object, required
    - `document` object, required
      - `id` string, required: Stable record id, e.g. `lse_012`.
      - `name` string, required
      - `kind` string, required: `lease`, `invoice`, `certificate`, `inspection_report` and the rest. This is the product’s own filing.
      - `mimeType` string, required
      - `size` number, required: Bytes.
      - `createdAt` string, required: ISO 8601 timestamp.
      - `links` object[], required: Every place the document is shown. A document can hang off any record, and off more than one; `folderId` is the folder that place files it in.
        - `kind` string, required
        - `id` string, required: Stable record id, e.g. `lse_012`.
        - `folderId` string: Stable record id, e.g. `lse_012`.
      - `expiresOn` string: Set on anything that expires, which is what feeds the compliance calendar.
      - `generated` boolean, required: True when the AI produced it rather than the owner uploading it.
      - `templateId` string: Stable record id, e.g. `lse_012`.
      - `language` 'en' | 'nl' | 'fr' | 'de': One of the four the product itself authors wording in: the clause library, the seeded messages, the words on a notice.
      - `folderId` string: No longer written. The folder is kept per place, on each of `links`.
      - `tags` string[], required
      - `status` 'withdrawn': `withdrawn` on a generated letter filed for a case that has since closed paid. Absent means the document stands.
      - `provenance` object, required
        - `actor` object, required
          - `kind` 'owner' | 'ai' | 'tenant' | 'contractor' | 'system' | 'channel', required: `ai` is Dardaris acting on the owner’s behalf. Everything it touches is marked.
          - `id` string: Stable record id, e.g. `lse_012`.
          - `name` string, required
        - `at` string, required: ISO 8601 timestamp.
        - `workflowRunId` string: Set when an automated run produced this, linking the record back to the run.
        - `reasoning` string: The rationale the AI recorded at the moment it acted.
  - `meta` object, required
    - `requestId` string, required: Echoed in the x-request-id header. Quote it in a bug report.

## Other responses

- `400`: A field is missing or out of range.
- `404`: A linked record is not in this portfolio.

---

[API](https://skmtc.dev/dardaris/apis/dardaris-api.md) · [All operations](https://skmtc.dev/dardaris/apis/dardaris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dardaris/apis/dardaris-api/revisions/4aff33835c73?raw)