Skip to main content
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:
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:
Key response fields:

​
get_file

Get detailed information about a specific file by ID. Parameters: Besides the file, it answers where the file stands: processing_status (processing, needs_review, completed, failed), current_step, needs_user_action, actions, review_url, reason, error, duplicate, and for a spreadsheet import_state, template_id, auto_import, import_session_id, sheet_selection, progress and rows_discarded. For a spreadsheet, import_state is where it stands from its upload to its rows saved, whether Leia or a person imports it: its step (upload, classify, sheet, read, columns, values, validate, submit, write), its status (running, waiting_person, done, failed), the reason it waits or failed for, who works it (actor: leia or user) and its session_id. current_step, processing_status and auto_import agree with it: while Leia works the file it is running and processing_status is processing. One question comes first: while current_step is awaiting_duplicate_review, the file repeats another one’s bytes, whatever import_state says. The same object as Get a File (v2) answers. Example prompts:

​
create_file_upload

Write. Start an upload. The MCP server runs remotely and cannot see your files: it returns a presigned URL, and the client sends the bytes straight to storage. A client that cannot send that PUT uses upload_file_content for small files. Returns file_id and upload (method, url, headers). Send every header unchanged, because they are part of the URL’s signature. The URL expires after expires_in_seconds (5 minutes):

​
complete_file_upload

Write. Confirm the PUT and start processing. It answers an error if the bytes are not in storage: start again from create_file_upload.

​
upload_file_content

Write. Upload a small file whose content goes in the call. For clients whose sandbox cannot reach storage or may not send the presigned PUT (claude.ai, Claude in the cloud): the bytes travel over the MCP connection you already authorized, and the server stores them and starts processing, as create_file_upload, the PUT and complete_file_upload do together. It answers like complete_file_upload, plus size_bytes and sha256 of what was stored. The server takes up to 2 MiB, but every byte goes through the assistant’s output, so in practice it suits files of some tens of KB. Larger files go through create_file_upload or the Files page in the app.

​
get_file_sheets

The tabs of a workbook, with their rows and dates, and Dcycle’s suggestion in selection.

​
open_import_session

Write. Open the import session of an uploaded spreadsheet, or reuse the one open for this file and template. A workbook with several tabs and no sheet_name answers an error with code SHEET_REQUIRED and the tabs. It imports nothing by itself. The MCP server has no tools for mapping, validating or submitting, so the session is finished in the app, or with dcy imports.

​
Workflow

Upload a file: create_file_upload, then the PUT from the client, then complete_file_upload, then get_file until it stops moving: for a spreadsheet, until import_state.status is no longer running; for any other file, until current_step stops moving. A client that cannot send the PUT calls upload_file_content instead of the first three steps. If a spreadsheet waits for a person on an importer step (import_state.status is waiting_person and its step is sheet, read, columns, values, validate or submit, or its reason is manual_mode): get_file_sheets for a workbook, then open_import_session. Not when import_state.reason is already_submitted, because that would import the data twice, nor for a support reason (owner_*, template_not_undoable, service_refused:<code>, auto_import_failed:<code>), nor while current_step is awaiting_duplicate_review: give the user review_url instead. When someone is already working on its session (no reason, actor is user or null), open it without another sheet_name, or their work is replaced. Read files:
  1. List files — list_files to find uploaded files by name, type, folder, or reading 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

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