> ## 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.

# File Tools

> MCP tools for querying uploaded files and their processing status

# File Tools

Query uploaded files — invoices, spreadsheets, and documents — along with their processing status and linked facilities. Files are the entry point for bulk data imports (purchases, invoices, employees, etc.).

## `list_files`

List uploaded files with optional filters by name, extension, status, or date range.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description                                                  |
| ----------------- | ------- | -------- | ----------- | ------------------------------------------------------------ |
| `organization_id` | string  | No       | default org | Organization UUID                                            |
| `name`            | string  | No       | —           | Filter by file name (partial match)                          |
| `extension`       | string  | No       | —           | Filter by extension: `pdf`, `xlsx`, `csv`, etc.              |
| `status`          | string  | No       | —           | Processing status: `pending`, `uploaded`, `error`, `deleted` |
| `from_date`       | string  | No       | —           | Filter from upload date (YYYY-MM-DD)                         |
| `to_date`         | string  | No       | —           | Filter until upload date (YYYY-MM-DD)                        |
| `page`            | integer | No       | 1           | Page number                                                  |
| `size`            | integer | No       | 50          | Results per page                                             |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "f3a1b2c4-...",
      "name": "invoices_q1_2025.xlsx",
      "extension": "xlsx",
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size_kb": 245,
      "status": "uploaded",
      "url": "https://storage.dcycle.io/...",
      "tags": ["invoices", "q1"],
      "organization_id": "a1b2c3d4-...",
      "folder_id": "d4c3b2a1-...",
      "linked_facilities": [
        { "id": "4cc2ac22-...", "name": "Madrid Office" }
      ],
      "linked_projects": [],
      "reading_status": "success",
      "current_step": null,
      "created_at": "2025-03-15T09:20:00"
    }
  ],
  "total": 128,
  "page": 1,
  "size": 50,
  "pages": 3
}
```

**Key response fields:**

| Field               | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `status`            | `pending` (uploading), `uploaded` (ready/processed), `error` (failed), `deleted` |
| `extension`         | File type: `pdf`, `xlsx`, `csv`, `xml`, etc.                                     |
| `size_kb`           | File size in kilobytes                                                           |
| `linked_facilities` | Facilities linked via invoice/waste data in the file                             |
| `reading_status`    | AI reading status for invoices: `success` or `error` (null if not read)          |
| `current_step`      | Current ingestion step (null if not actively being processed)                    |
| `tags`              | User-assigned labels                                                             |

## `get_file`

Get detailed information about a specific file by ID.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description       |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `file_id`         | string | **Yes**  | —           | UUID of the file  |
| `organization_id` | string | No       | default org | Organization UUID |

**Example prompts:**

```
"List all PDF files uploaded this month"
"Show me files with errors"
"What files were uploaded for our Madrid office?"
"List CSV files from last week"
"What's the processing status of file abc-123?"
"Show recently uploaded invoices"
```

## Workflow

1. **List files** — `list_files` to find uploaded files by name, type, or status
2. **Check details** — `get_file` for a specific file's processing state
3. **Check processing** — `list_processing_jobs` to see if a file upload triggered calculations and their status
4. **View imported data** — Use the corresponding data tool (e.g. `list_invoices`, `list_purchases`) to see records created from the file

## Related

<CardGroup cols={2}>
  <Card title="Processing Jobs" icon="spinner" href="/mcp/processing-jobs">
    Track file upload processing and calculation status
  </Card>

  <Card title="Invoices" icon="file-invoice" href="/mcp/invoices">
    Invoice data often imported via file uploads
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/files/overview">
    REST API endpoints for file management
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/files">
    Upload and manage files from the command line
  </Card>
</CardGroup>