Skip to main content
The Files Management Sub-system allows you to manage file resources within the Lucca Public API. A file resource represents a file that can be uploaded, stored, and retrieved through the API. A file can either be retrieved as a JSON representation of its metadata ; or downloaded as a binary stream.

Getting Access to a File

In order to get access to a file, either its JSON representation or its actual content, you need:
  • to authenticate with a valid access token (see Authentication);
  • to have either files.readonly or files.readwrite scope granted to your access token;
  • to have a complementary token, that can only be given in the context of the API object that is related to this file and that must be passed in query parameters in order to GET /files/{id}.
This complementary token can only be retrieved via the resource that directly references this file, and it is bound to the API client that read that resource: follow the link with the same Authorization header. The token does not authenticate you on its own, and another API client cannot use it. Every resource that references files (an employee-attribute whose value holds a file, an employment or a job-position with a document, an employee with a portrait) returns their download links under links.files, indexed by file id, when you send ?include=links. Each entry holds an href that returns the file content, the token it carries, and the expiresAt instant past which it stops working. Read the resource again to get a fresh link; do not store href. An entry is null when you may not download that file: skip it. href carries an explicit disposition=attachment, which supersedes your Accept header: following it always returns the file content, even with Accept: application/json. To get the file’s JSON representation instead, build your own URL from the token, with disposition=json (see below). For example, an employee-attribute holding a scanned document:
The url of a file reference ("url": "https://example.ilucca.net/lucca-api/files/9154c6a2-6105-4d5d-bfb6-5fd2d54037b3" above) does not give access to the file: always go through links.files. On a collection, each item holds the links to its own files.

Employee Portraits

An employee’s portrait is a picture file: its id is the id of that file. Like any other file, download it through its entry in links.files, returned with ?include=links.

Deprecated Download Means

Before links.files, files were downloaded through the following means. They still work, but are deprecated: use links.files instead. To get the content through a deprecated link, set the disposition query parameter to attachment or inline (see below).

Viewing a File: JSON vs Raw Content

When retrieving a file via GET /files/{id}, you can either get its JSON representation (metadata) or its raw content (binary stream). By default, the API will return the file metadata in JSON format. To get the raw content of the file, you need to set the Accept header to application/octet-stream or another appropriate MIME type (typically the one returned by the JSON metada in response.contentType). When the Accept header is cannot be set, you can also use the disposition query parameter to specify how the file should be handled by the client. When set to inline or attachment, the API will return the raw content of the file accordingly.

Uploading a File

To upload a file to Lucca, you can use the POST /lucca-api/files endpoint. You need to send a multipart/form-data request containing the file to be uploaded. Make sure to authenticate with a valid access token that has the files.readwrite scope, as well as set up the multipart boundary and content correctly. The stored file name comes from the filename parameter of the multipart Content-Disposition header, not from the name of the file on your disk. You are free to set it to any value: this lets you store a file under a meaningful name in a single request, without having to rename it beforehand.
File names are sanitized on upload: the characters < > [ ] { } " ' ; = | and the backtick are replaced with an underscore (_).