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. For example: an employee has a portrait, which is a reference to a file. In order to retrieve said file, you need to get the portrait link from the employee resource (which will only be returned by the server if you send ?include=links). This link contains a token query parameter that is required to access the file. 
GET /lucca-api/employees/416?include=links HTTPS/2
Host: example.ilucca.net
Authorization: Bearer XXX

> Response 200 OK
Content-Type: application/json

{
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416",
    "givenName": "John",
    "familyName": "Doe",
    "portrait": {
        "id": "2face165-5345-4cf3-ab05-5421a6b19df2",
        "type": "file",
        "url": "https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2",
    },

    "links": {
        "portrait":  {
            "href": "https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9"
        }
    }
}

​
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. 
GET /lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 HTTPS/2
Host: example.ilucca.net
Authorization: Bearer XXX
Accept: */*

> Response 200 OK
Content-Type: application/json

{
    "id": "2face165-5345-4cf3-ab05-5421a6b19df2",
    "type": "file",
    "url": "https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2",
    "fileName": "portrait.png",
    "contentType": "image/png",
    "size": 34567,
    "createdAt": "2024-01-15T10:20:30Z"
}

​
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. 
POST /lucca-api/files HTTPS/2
Host: example.ilucca.net
Authorization: Bearer XXX
Content-Type: multipart/form-data; boundary=----boundary7MA4YWxkTrZu0gW
------boundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="portrait.png"

...binary content...

------boundary7MA4YWxkTrZu0gW--

> Response 201 Created
Content-Type: application/json
Location: https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2
{
    "id": "2face165-5345-4cf3-ab05-5421a6b19df2",
    "type": "file",
    "url": "https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2",
    "fileName": "portrait.png",
    "contentType": "image/png",
    "size": 34567,
    "createdAt": "2024-01-15T10:20:30Z"
}