File Download By Id

Quick Links

Accounts Accounting Entries Products Customers Sales quotes Sales invoices Suppliers Purchase invoices

This feature is currently under development and, although not available in the current version, its preliminary documentation is provided to give you a preview of the enhancements that will be included in an upcoming update.

HTTP Operation Type Object DTO Why-DTOs?
(Query) files EntityFile

Description

The File Download by Id page illustrates a common use case of the files query.
It focuses on scenarios where you already know the file ID (for example, obtained from a previous files query) and you need to retrieve short-lived link paths (downloadPath and previewPath) to access the file.

This pattern is typically used when:

  • You first list files with metadata only (without requesting link paths).
  • Later, when a user selects a file to open, you run a new files query filtered by its ID to get a fresh valid link.

The returned link paths are temporary and must be consumed quickly:

  • downloadPath always forces download of the file (due to the Content-Disposition: attachment header).
  • previewPath displays the file inline when possible, with optional HTML previews for .csv, .xml, and .txt.

img

The files query returns short-lived link paths (downloadPath and previewPath) for all files matching the filter criteria.

Because these paths are temporary, retrieving a file ID from an initial files query and then executing a second files query filtered by that ID is only necessary when the link might have expired.

For example, if you want to display in an interface the list of file names attached to a customer or an accounting entry, the initial files query can return the file IDs and metadata without requesting the link paths.
Later, when a user clicks on one of the files to download or preview it, you would run a new files query filtered by the chosen file ID to obtain a fresh valid link.

On the other hand, if your scenario requires fetching a list of files and immediately downloading or previewing them, you can request the link paths directly in the first files query, since the links will still be valid during that short workflow.

How to download a file by ID ?

GraphQL Query
query ($Id: String!) {
  files(where: { id: { eq: $Id } }) {
    edges {
      node {
        id
        fileName
        type
        mimeType
        size
        downloadPath
        previewPath
      }
    }
  }
}
Variables
{
  "Id": "98f7adc7dd104cd984f9c113ef9a8e54.pdf"
}
Example Response
{
  "data": {
    "files": {
      "edges": [
        {
          "node": {
            "id": "98f7adc7dd104cd984f9c113ef9a8e54.pdf",
            "fileName": "invoice-q1.pdf",
            "type": "pdf",
            "mimeType": "application/pdf",
            "size": 2497741,
            "downloadPath": "/files/LqTJRFny",
            "previewPath": "/files/pR4mGwVe"
          }
        }
      ]
    }
  }
}

To actually access the file:

  • Prefix downloadPath or previewPath with the API base URL (without /graphql).
  • Call the resulting URL with a simple HTTP GET.

Examples:

  • https://<api>/files/LqTJRFny → returns the raw file stream
  • https://<api>/files/pR4mGwVe → returns an HTML preview for supported formats (.csv, .xml, .txt)

You can:

  • Open the URL directly in a web browser
  • Use fetch or curl in a script to retrieve the content
Key Value
Authorization Bearer Current access Token How to find?
X-TenantId Current tenant id How to find?
X-OrganizationId Current organization Id How to find?
x-api-key Primary or secondary subscription key of your app How to find?

file (context by id)

Fields Type Description Length
id String File ID  
fileName String Name of the uploaded file 255
type String File extension (e.g., pdf, jpg, xml) 10
mimeType String MIME type of the file (e.g., application/pdf) 100
size Int File size in bytes  
downloadPath String Temporary relative short path to download the file. 255
previewPath String Temporary relative short path to preview the file (CSV, XML, TXT). 255
Info

  • id : Note that the File ID is a string and not a UUID. For example, it can have the format 98f7adc7dd104cd984f9c113ef9a8e54.pdf. Use the files query with the id filter whenever you already know the file ID and just need a download link.

  • downloadPath: A temporary relative short path to download the file.
    • Example: /files/LqTJRFny
    • It is valid for 10 minutes.
    • The GraphQL query returns only metadata and the link, not the file content itself.
    • To use this path as a short link, prefix it with the base URL of the API (without the /graphql path).
    • The backend always returns the header Content-Disposition: attachment, which instructs browsers to download the file instead of displaying it inline.
    • Behind this short link, the file stream of the requested file is returned.
  • previewPath: A temporary relative short path to preview the file.
    • Example: /files/aZ3kTyPq
    • Unlike downloadPath, the backend does not include a Content-Disposition: attachment header. This allows browsers to try to display the file inline whenever possible.
    • For .csv, .xml, and .txt files, an HTML preview layout is generated when a tabular structure or valid XML is detected, so the browser displays a readable table.
    • Other file types such as PDFs and images are streamed as is.
    • It is valid for 10 minutes.
    • The GraphQL query returns only metadata and the link, not the file content itself.
    • To use this path as a short link, prefix it with the base URL of the API (without the /graphql path).
    • Behind this short link, a file stream is returned.

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:

HTTP URL Example Description
https://<apidomain>/graphql Standard GraphQL call (e.g., files or filesExport query via POST body).
https://<apidomain>/files/LqTJRFny Direct call to a link path to retrieve the file stream.
Errors
Status Error message
404 The link path has expired. Please request a new link and try again.
404 The associated file could not be found. It may have been removed.