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)

{
  "items": {
    "id": "<string>",
    "name": "<string>",
    "extension": "<string>",
    "mime_type": "<string>",
    "size_kb": 123,
    "folder_id": {},
    "status": "<string>",
    "url": "<string>",
    "tags": {},
    "category": {},
    "classifications": {
      "id": "<string>",
      "document_type": "<string>",
      "category": "<string>",
      "confidence_level": 123,
      "custom_label": {},
      "reading": {},
      "linked": true
    },
    "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)

{
  "items": {
    "id": "<string>",
    "name": "<string>",
    "extension": "<string>",
    "mime_type": "<string>",
    "size_kb": 123,
    "folder_id": {},
    "status": "<string>",
    "url": "<string>",
    "tags": {},
    "category": {},
    "classifications": {
      "id": "<string>",
      "document_type": "<string>",
      "category": "<string>",
      "confidence_level": 123,
      "custom_label": {},
      "reading": {},
      "linked": true
    },
    "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:

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

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: the file’s document type split by :: (e.g. ["invoice", "water"]). Empty when the file has no classification, or more than one (see classifications).

string | null

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. null when the file has no classification, or more than one.

array[object]

Every classification of the file, each with its own reading, ordered by document type. Today every file has at most one, so the list has one entry that repeats tags, category, reading and linked.

Show Classification Item

string

Classification UUID.

string

Document type as stored (e.g. invoice::water).

string

Category of the document type, with the labels from before the merge reported as the current one (stationary_combustion for a stored invoice::gas).

number

Confidence of the classification, between 0 and 1. 1 once a person confirmed it.

string | null

Label given to a file that is kept as a reference document.

object | null

The reading extracted for this classification, with the same shape as the item’s reading. null while it has not been read.

boolean

true if records were already created from this classification’s reading.

boolean

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

object | null

Parsed reading data. null if processing has not completed, or if the file has more than one classification (each reading is then in classifications).

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). 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, Spanish electricity only decisions, or org_history; readings stored before decisions existed may carry jev for the same approximate step), its confidence and the query text. org_history (electricity and water) is the supplier your organization confirmed for the same issuer when saving earlier reviews; it also carries votes (how many reviewed documents confirmed it) and key (tax when the issuer was recognized by its tax id, name when by its name), and its confidence is null. The supplier_match 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.

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"
            }
          ]
        }
      },
      "classifications": [
        {
          "id": "44444444-4444-4444-4444-444444444444",
          "document_type": "invoice::water",
          "category": "water",
          "confidence_level": 0.97,
          "custom_label": null,
          "linked": false,
          "reading": {
            "id": "22222222-2222-2222-2222-222222222222",
            "status": "success",
            "content": {"items": ["..."]}
          }
        }
      ]
    }
  ],
  "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"}

Every file has one classification today, and no endpoint adds a second one yet. classifications is the groundwork for documents that bill several services (water and gas on one invoice): such a file will have one classification and one reading per service, and its tags, category and reading will be empty. Read classifications now and your integration will not need to change.
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

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​Related Endpoints

Upload Files

Update Reading

Create Records

Retry Processing

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

Related Endpoints