> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload and download contract originals, invoices, receipts, and other evidence.

File upload is a three-step flow — the API never accepts a raw file body directly. All three
steps require `contract_view` (view) and a bearer token.

<Steps>
  <Step title="Presign">
    `POST /files/presign` requests a signed upload URL and an upload token.

    <ParamField body="fileName" type="string" required />

    <ParamField body="contentType" type="string" required />

    <ParamField body="sizeBytes" type="integer" required>Minimum 0.</ParamField>

    <ParamField body="kind" type="string" required>
      Must be one of the tenant's allowed file kinds (contract originals, invoices, receipts,
      acceptance reports, and other evidence types).
    </ParamField>

    <ParamField body="subjectId" type="string" />

    <ParamField body="contractId" type="string" />

    <ParamField body="paymentId" type="string" />
  </Step>

  <Step title="Upload">
    `PUT` the file bytes directly to the signed URL returned by the presign step. Alforse's API
    is not in this request path — this goes straight to object storage.
  </Step>

  <Step title="Confirm">
    `POST /files/confirm` tells the API the upload finished, so it can verify the object,
    trigger scanning, and record file metadata.

    <ParamField body="bucket" type="string" />

    <ParamField body="objectKey" type="string" required />

    <ParamField body="fileName" type="string" required />

    <ParamField body="contentType" type="string" required />

    <ParamField body="sizeBytes" type="integer" required />

    <ParamField body="kind" type="string" required />

    <ParamField body="subjectId" type="string" />

    <ParamField body="contractId" type="string" />

    <ParamField body="paymentId" type="string" />

    <ParamField body="uploadToken" type="string" required>
      The token returned by the presign step.
    </ParamField>
  </Step>
</Steps>

## Download a file

`GET /files/:id/download` · requires `contract_view` (view)

<ParamField query="contractId" type="string" />

<ParamField query="paymentId" type="string" />

Every download is authorized server-side against the requesting user's tenant and subject
scope, and is subject to the file-scan policy configured by `FILE_SCAN_MODE` and
`FILE_DOWNLOAD_REQUIRES_CLEAN_SCAN` — see [Configuration](/configuration#file-scanning-and-download-gating).
A file that hasn't cleared scanning yet may not be downloadable depending on that policy.

See [Contract Intake](/guides/contract-intake) for how this flow fits into creating a contract
from a scanned PDF, and [Evidence Trail](/guides/evidence-trail) for how uploaded files surface
later.