List File Readings

Retrieve extracted file readings produced by the asynchronous document processing pipeline

GET /v1/files/readings

List File Readings

JavaScript

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

200

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

← Files

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

Request

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

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, stationary_combustion, recharges, or wastes. gas and fuel_delivery are the stationary-combustion labels of files classified before they merged; any of the three matches all of them.

page · integer

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

size · integer

Page size for folder-style browsing.

Response

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

items · array[object]

List of file reading entries.

Show File Reading Item

id · string

File UUID.

name · string

Original file name (without extension).

extension · string

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

mime_type · string

MIME type of the uploaded file.

size_kb · number

File size in kilobytes.

folder_id · string | null

Folder UUID if the file is in a folder.

status · string

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

url · string

Presigned download URL for the file.

tags · array[string]

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

category · string

Derived category: water, electricity, stationary_combustion, recharges, or wastes. Files classified before the merge of gas bills and fuel deliveries report gas or fuel_delivery.

linked · boolean

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

reading · object | null

Parsed reading data. null if processing has not completed.

Show Reading Object

id · string

File reading UUID.

status · string

Processing status: success or error.

content · object

Extracted content from OCR or LLM processing.

Show Content Object

items · array[object]

Extracted line items. Shape varies by category (e.g. invoice fields for energy, waste fields for wastes). Electricity, stationary combustion and water items may also carry issuer_legal_name and issuer_tax_id (the issuing supplier as printed) and a supplier_match object: when the backend filled supplier_id, the method used (exact, legal_name_exact, legal_form_tiebreak or, electricity only, jev), its confidence and the query text. The key is present as null when the backend tried and no supplier matched, and absent when it did not try (no country read, or a reading stored before supplier matching). Stationary combustion items also carry printed_fuel_name, the product as printed (e.g. TECNODIESEL E+10); their stationary_fuel_id is null when the fuel read in fuel_name contradicts it, so the fuel has to be chosen before the record calculates.

total · integer

Total number of matching items.

page · integer

Current page number.

size · integer

Page size.

Example

cURL

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

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

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

Related Endpoints

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