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

# Files

> Upload, confirm, inspect, and manage organization-scoped files

# Files

The Files API stores organization-scoped documents in S3 and tracks their metadata in PostgreSQL.

Use the presigned upload flow when you want clients, scripts, or CI jobs to upload files autonomously and trigger downstream classification.

## Authentication

All endpoints require:

* `x-api-key`
* `x-organization-id`

## Recommended Upload Flow

<CardGroup cols={2}>
  <Card title="Upload Files" icon="cloud-arrow-up" href="/api-reference/files/upload">
    Request presigned URLs, upload bytes directly to S3, then confirm the upload to trigger classification.
  </Card>

  <Card title="List File Readings" icon="sparkles" href="/api-reference/files/readings">
    Retrieve extracted file readings after the async classification and processing steps complete.
  </Card>
</CardGroup>

## Core Endpoints

| Endpoint                               | Method   | Purpose                                                                   |
| -------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `/v1/files/presigned-urls`             | `POST`   | Create pending file records and return presigned S3 upload URLs           |
| `/v1/files/batch-update`               | `PATCH`  | Mark uploads as `uploaded` or `error` after the S3 step                   |
| `/v1/files/upload`                     | `POST`   | Legacy/simple multipart upload through the backend                        |
| `/v1/files`                            | `GET`    | List files in the active organization                                     |
| `/v1/files/{file_id}`                  | `GET`    | Fetch one file with metadata                                              |
| `/v1/files/send-event`                 | `POST`   | Manually re-trigger file processing events such as `PROCESS_DOCUMENT`     |
| `/v1/files/readings`                   | `GET`    | List extracted file readings or fetch readings for specific file IDs      |
| `/v1/files/readings/{file_reading_id}` | `PUT`    | Update extracted reading content before creating records                  |
| `/v1/files/readings`                   | `POST`   | Create invoices or wastes from a file reading and link them to facilities |
| `/v1/files/{file_id}`                  | `DELETE` | Soft-delete a file                                                        |
| `/v1/files/{file_id}/recover`          | `PUT`    | Recover a soft-deleted file                                               |

## Status Lifecycle

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
pending -> uploaded -> async classification / processing
    |
    +-> error
    +-> deleted
```

## Notes

* `folder_id` is optional on upload requests. Omit it to upload at the root level.
* `project_id` is optional on `PATCH /v1/files/batch-update`. When present, the backend creates `file_project` links.
* `POST /v1/files/upload` is still available, but the presigned flow is recommended for automation and large-file friendly clients.
* `POST /v1/files/send-event` can be used to manually retry downstream processing when a classified file has not produced a
  `file_reading` yet.
* Once processing finishes, clients can use `GET /v1/files/readings`, optionally edit extracted values with `PUT /v1/files/readings/{file_reading_id}`, and then create linked invoices or wastes with `POST /v1/files/readings`.
* `POST /v1/files/readings` currently supports one file reading per request, even though the request body accepts an array.

## Related Documentation

<CardGroup cols={2}>
  <Card title="MCP Tools" icon="robot" href="/mcp/files">
    Access file data from AI assistants via MCP
  </Card>

  <Card title="Invoices API" icon="file-invoice" href="/api-reference/invoices/overview">
    Manage invoices created from file readings
  </Card>
</CardGroup>