Skip to main content

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

Upload Files

Request presigned URLs, upload bytes directly to S3, then confirm the upload to trigger classification.

List File Readings

Retrieve extracted file readings after the async classification and processing steps complete.

​
Core Endpoints

EndpointMethodPurpose
/v1/files/presigned-urlsPOSTCreate pending file records and return presigned S3 upload URLs
/v1/files/batch-updatePATCHMark uploads as uploaded or error after the S3 step
/v1/files/uploadPOSTLegacy/simple multipart upload through the backend
/v1/filesGETList files in the active organization
/v1/files/{file_id}GETFetch one file with metadata
/v1/files/send-eventPOSTManually re-trigger file processing events such as PROCESS_DOCUMENT
/v1/files/readingsGETList extracted file readings or fetch readings for specific file IDs
/v1/files/readings/{file_reading_id}PUTUpdate extracted reading content before creating records
/v1/files/readingsPOSTCreate invoices or wastes from a file reading and link them to facilities
/v1/files/{file_id}DELETESoft-delete a file
/v1/files/{file_id}/recoverPUTRecover a soft-deleted file

​
Status Lifecycle

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.