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, reading status, folder, or project. By default this returns every file in the organization regardless of which folder it sits in. Pass folder_id to walk the folder hierarchy instead — that switches flattening off, since the two cannot be applied at the same time. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`name`	string	No	—	Filter by file name (partial match, also matches the tag label)
`extension`	string	No	—	Filter by extension: `pdf`, `xlsx`, `csv`, etc.
`item_type`	string	No	`file`	`file` or `folder`; omit to return both
`reading_status`	string[]	No	—	Any of `unread`, `linked`, `success`, `error`, `pending`
`document_type`	string[]	No	—	Classification, e.g. `invoice::electricity`
`folder_id`	string	No	—	List one folder’s contents; disables flattening
`project_id`	string	No	—	Only files linked to this project
`owner_id`	string	No	—	Only files uploaded by this user
`is_deleted`	boolean	No	`false`	List the trash instead of active files. Cannot be combined with `project_id`
`flatten`	boolean	No	`true`	Ignore the folder hierarchy. Set `false` to list only root-level items
`include_children`	boolean	No	`false`	Also include files from child organizations
`sort`	string[]	No	—	e.g. `-created_at` for newest first
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page

reading_status maps to the tabs on the Files page: Processed is success, Errors is error. Use is_deleted: true for the Trash tab.

Example response:

{
  "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`	`uploaded` for active files, or `deleted` when listing with `is_deleted: true`
`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 in this organization"
"Show me files with errors"
"What files were uploaded for our Madrid office?"
"Show the newest 20 files"
"What's the processing status of file abc-123?"
"What's in the trash?"

Workflow

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

Processing Jobs

Track file upload processing and calculation status

Invoices

Invoice data often imported via file uploads

API Reference

REST API endpoints for file management

CLI

Upload and manage files from the command line

Getting Started

Tools Reference

Reference Data

File Tools

File Tools

`list_files`

`get_file`

Workflow

Processing Jobs

Invoices

API Reference

CLI

​File Tools

​list_files

​get_file

​Workflow

​Related

Processing Jobs

Invoices

API Reference

CLI

File Tools

`list_files`

`get_file`

Workflow

Related