Skip to main content
GET
/
v1
/
files
/
readings
List File Readings
const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/files/readings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​
List File Readings

Use this endpoint after uploading and confirming a file to retrieve the parsed reading payload generated by the file processing pipeline. This is the entry point for programmatic post-upload automation:
  1. Upload file
  2. Wait for async classification and processing
  3. Fetch extracted readings
  4. Optionally edit the reading
  5. Create linked invoices or wastes from the reading

​
Headers

​
x-api-key
string
required
API key for authentication.
​
x-organization-id
string
required
Organization UUID that owns the uploaded files.

​
Query Parameters

​
file_id
string[]
Optional file UUID list. When provided, the endpoint returns readings for those files instead of folder-style browsing.
​
folder_id
string
Optional folder UUID to browse readings within a folder.
​
project_id
string
Optional project UUID to filter readings to a project.
​
linked
boolean
Filter by whether the file already has linked invoices or wastes.
​
name
string
Case-insensitive file name search.
​
category
string[]
Optional reading categories. Values come from the file reading categories returned by the API, such as water, electricity, gas, fuel_delivery, recharges, or wastes.
​
page
integer
Page number for folder-style browsing. Defaults to 1.
​
size
integer
Page size for folder-style browsing.

​
Response Shape

The response mixes folders and file reading items. File reading items include:
  • id: file UUID
  • name: file name
  • tags: classifier tags such as invoice::water
  • category: derived category string
  • reading.status: processing status, usually success or error
  • reading.content.items: extracted OCR or LLM output
  • linked: true once invoices or wastes have been created from the file

​
Example

curl -X GET "https://api.dcycle.io/v1/files/readings?file_id=11111111-1111-1111-1111-111111111111" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Example Response

{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "invoice_march",
      "extension": "pdf",
      "mime_type": "application/pdf",
      "size_kb": 248,
      "folder_id": null,
      "status": "uploaded",
      "url": "https://...",
      "tags": ["invoice", "water"],
      "category": "water",
      "linked": false,
      "reading": {
        "id": "22222222-2222-2222-2222-222222222222",
        "status": "success",
        "content": {
          "items": [
            {
              "invoice_number": "WTR-2024-03",
              "quantity": 32.1,
              "unit": "cubic_metre_(m3)",
              "start_date": "2024-03-01",
              "end_date": "2024-03-31"
            }
          ]
        }
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 1
}

​
Notes

  • This endpoint does not trigger processing. It only returns the current reading state.
  • linked=true means downstream invoices or wastes already exist for the file.
  • When file_id is provided, the response is effectively a direct fetch for those file readings.