Files

Description

The Files query returns a list of information about files previously uploaded using the uploadFileToEntity mutation, or generated/uploaded directly from Sage Active.
For each file, details such as fileName, mimeType, uploadDate, size, and related entity information are provided.
It supports advanced filtering, sorting, and pagination on fields such as entityType, entityId, businessDate, and fileName.

This query is useful for multiple scenarios:

• Retrieving all document records linked to business entities (e.g., all invoices attached to an accounting entry)
• Retrieving information about a specific file by its id (to check metadata or availability)
• Checking whether an uploaded file has been fully processed and is safe to use (via id filter, useful right after an upload)
• Listing files generated by an filesExport request

As each uploaded file undergoes an antivirus scan, the query response normally includes only processed and safe files.

• Files that are still being processed (pending upload submission or antivirus scan results) or that have been rejected as infected are excluded from the response.
• Exception: when filtering explicitly by id, the query may also return files that are still being processed, allowing you to check the status of a recently uploaded file.

If explicitly requested, each file entry can include short-lived access paths:

• downloadPath: a temporary relative path to download the file.
• previewPath: a temporary relative path to preview the file content in a browser.

These short paths are valid only for a limited time and should be used promptly after retrieval.

Filtering

The query supports the following filtering options:

• entityType: Filter by business entity type (e.g. Customer, Supplier, AccountingEntry)
• entityId: Filter by the ID of the target entity
• fileName: Partial name search (e.g. contains: "invoice")
• type: Filter by the file extension (e.g., pdf, jpg, xml)
• businessDate: Filter by business date range (gte, lte)
• uploadDate: Filter by file upload date range
• id: Filter by file id (used to check the status of the upload process)
• filesExport When set to true, returns only files generated by filesExport.

Filtering Restrictions

Due to technical constraints, the query only supports a limited and controlled set of filtering options.
Any unsupported combination may result in errors or ignored filters.

Supported Filters

Not Supported

• ❌ OR logic is not allowed between multiple filters — only AND at root level
• ❌ Multiple eq clauses on the same field to simulate OR (use in instead)
• ❌ Deeply nested groupings (and: [{...}, {...}]) beyond a flat array are discouraged

Ordering

The query supports ordering results in ASC or DESC order for the following fields:

• businessDate: Orders results by the business date of the file

Ordering Restrictions

Due to technical constraints, only a limited and controlled set of orderings are supported.

Supported Orderings

Not Supported

• ❌ Ordering by fields other than those listed above

Pagination

The query supports cursor-based pagination using the first argument.

Pagination Restrictions

• The maximum allowed value for first is 500, to remain consistent with other query operations in the API.
• Even when first: 500 is passed, the API internally returns the data in chunks of 100 files.
• Pagination is not available with last.
• The default value for pagination is 20, consistent with other query operations in the API.

Supported Pagination

Not Supported

• ❌ Pagination using last
• ❌ Values above 500 for first

query {
  files(
    order: { businessDate: DESC },
    where: {
        entityType: { eq: ACCOUNTING_ENTRY }
        entityId: { eq: "8b21a143-4d9c-41ea-b1dc-1cf9d91a72f1" }
        businessDate: { gte: "2024-01-01" }
        businessDate: { lte: "2025-04-30" }
        fileName: { contains: "invoice" }
        type: { eq: "pdf" }
    },
    first: 10
  ) {
    edges {
      node {
        id
        fileName
        type
        mimeType
        size
        businessDate
        comment
        uploadDate
        entityType
        entityId
        downloadPath
        previewPath
      }
    }
  }
}

{
  "data": {
    "files": {
      "edges": [
        {
          "node": {
            "id": "98f7adc7dd104cd984f9c113ef9a8e54.pdf",
            "fileName": "invoice-q1.pdf",
            "type": "pdf",
            "mimeType": "application/pdf",
            "size": 2497741,
            "businessDate": "2025-04-04T00:00:00Z",
            "comment": "Invoice for Q1",
            "uploadDate": "2025-04-04T08:12:43Z",
            "entityType": "ACCOUNTING_ENTRY",
            "entityId": "8b21a143-4d9c-41ea-b1dc-1cf9d91a72f1",
            "downloadPath": "/files/LqTJRFny",
            "previewPath": "/files/pR4mGwVe",
          }
        }
      ]
    }
  }
}

query {
  files(
    order: { uploadDate: DESC },
    where: {
      filesExport: { eq: true }
    }
  ) {
    edges {
      node {
        id
        fileName
        type​ ​ 
        mimeType
        size
        uploadDate
        downloadPath
        previewPath
        filesExport
      }
    }
  }
}

{
  "data": {
    "files": {
      "edges": [
        {
          "node": {
            "id": "d2c33b7f-4c89-4e21-9f6e-1a75a1f4f8aa.csv",
            "fileName": "index.csv",
            "type": "csv",
            "mimeType": "text/csv",
            "size": 1842,
            "uploadDate": "2025-09-15T10:05:23Z",
            "downloadPath": "/files/LqTJRFny",
            "previewPath": "/files/aZ3kTyPq",
            "filesExport": true
          }
        },
        {
          "node": {
            "id": "7a5b91d2-8e72-4d3a-92ac-3dbcf76f3214.zip",
            "fileName": "archives.zip",
            "type": "zip",
            "mimeType": "application/zip",
            "size": 6543210,
            "uploadDate": "2025-09-15T10:05:24Z",
            "downloadPath": "/files/M8rNfVxJ",
            "previewPath": "/files/pR4mGwVe",
            "filesExport": true
          }
        }
      ]
    }
  }
}

Header

files

Using link paths

Link paths are consumed with a simple HTTP GET.
Build the URL by prefixing the downloadPath or previewPath with the API base URL (without /graphql).
The response is always a file stream, so the URL can be opened directly in a web browser.

Unlike standard GraphQL queries, which are always executed with a POST on the /graphql endpoint, link paths are consumed with a direct GET on /files/....
The comparison below highlights this difference:

• downloadPath: forces the browser to download the file (due to the Content-Disposition: attachment header).
• previewPath: displays the file inline whenever possible.
  COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability For .csv, .xml, or .txt, the backend may return an HTML preview; other types are streamed as is.

Errors