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));

import requests

url = "https://api.dcycle.io/v1/files/readings"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/files/readings \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {
    "id": "<string>",
    "name": "<string>",
    "extension": "<string>",
    "mime_type": "<string>",
    "size_kb": 123,
    "folder_id": {},
    "status": "<string>",
    "url": "<string>",
    "tags": {},
    "category": "<string>",
    "linked": true,
    "reading": {
      "id": "<string>",
      "status": "<string>",
      "content": {
        "items": {}
      }
    }
  },
  "total": 123,
  "page": 123,
  "size": 123
}

GET

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));

import requests

url = "https://api.dcycle.io/v1/files/readings"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/files/readings \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {
    "id": "<string>",
    "name": "<string>",
    "extension": "<string>",
    "mime_type": "<string>",
    "size_kb": 123,
    "folder_id": {},
    "status": "<string>",
    "url": "<string>",
    "tags": {},
    "category": "<string>",
    "linked": true,
    "reading": {
      "id": "<string>",
      "status": "<string>",
      "content": {
        "items": {}
      }
    }
  },
  "total": 123,
  "page": 123,
  "size": 123
}

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:

Upload file
Wait for async classification and processing
Fetch extracted readings
Optionally edit the reading
Create linked invoices or wastes from the reading

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

string[]

Optional file UUID list. When provided, the endpoint returns readings for those files instead of folder-style browsing.

string

Optional folder UUID to browse readings within a folder.

string

Optional project UUID to filter readings to a project.

boolean

Filter by whether the file already has linked invoices or wastes.

string

Case-insensitive file name search.

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.

integer

Page number for folder-style browsing. Defaults to 1.

integer

Page size for folder-style browsing.

Response

Returns a paginated list of file reading items (HTTP 200).

array[object]

List of file reading entries.

Show File Reading Item

string

File UUID.

string

Original file name (without extension).

string

File extension (e.g. "pdf", "xlsx").

string

MIME type of the uploaded file.

number

File size in kilobytes.

string | null

Folder UUID if the file is in a folder.

string

File upload status (e.g. "uploaded").

string

Presigned download URL for the file.

array[string]

Classifier tags (e.g. ["invoice", "water"]).

string

Derived category: water, electricity, gas, fuel_delivery, recharges, or wastes.

boolean

true if invoices or wastes have already been created from this file.

object | null

Parsed reading data. null if processing has not completed.

Show Reading Object

string

File reading UUID.

string

Processing status: success or error.

object

Extracted content from OCR or LLM processing.

Show Content Object

array[object]

Extracted line items. Shape varies by category (e.g. invoice fields for energy, waste fields for wastes).

integer

Total number of matching items.

integer

Current page number.

integer

Page size.

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}"

import os
import requests

response = requests.get(
    "https://api.dcycle.io/v1/files/readings",
    headers={
        "x-api-key": os.environ["DCYCLE_API_KEY"],
        "x-organization-id": os.environ["DCYCLE_ORG_ID"],
    },
    params={
        "file_id": ["11111111-1111-1111-1111-111111111111"],
    },
    timeout=30,
)

payload = response.json()
print(payload["items"][0]["reading"]["content"]["items"])

const axios = require('axios');

axios.get('https://api.dcycle.io/v1/files/readings', {
  headers: {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  },
  params: {
    file_id: '11111111-1111-1111-1111-111111111111',
  },
}).then(response => {
  const items = response.data.items[0].reading.content.items;
  console.log(items);
});

Successful 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
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

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.

Upload Files

Upload files via presigned S3 URLs

Update Reading

Edit extracted content before creating records

Create Records

Convert readings into invoices or wastes

Retry Processing

Re-queue a stalled file for processing

Retry File Processing Update File Reading

​List File Readings

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​Notes

​Related Endpoints

Upload Files

Update Reading

Create Records

Retry Processing

List File Readings

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

Notes

Related Endpoints