> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Introduction to the Files Management Sub-system.

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](/documentation/using-api/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.

<CodeGroup>
  ```http theme={null}
  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"
          }
      }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```http GET JSON (Accept) theme={null}
  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"
  }
  ```

  ```http GET JSON (?disposition=json) theme={null}
  GET /lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9&disposition=json HTTPS/2
  Host: example.ilucca.net
  Authorization: Bearer XXX

  > 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"
  }
  ```

  ```http GET Content (Accept) theme={null}
  GET /lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 HTTPS/2
  Host: example.ilucca.net
  Authorization: Bearer XXX
  Accept: application/octet-stream
  ```

  ```http GET Content (?disposition=inline) theme={null}
  GET /lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9&disposition=inline HTTPS/2
  Host: example.ilucca.net
  Authorization: Bearer XXX

  > Response 200 OK
  Content-disposition: inline; filename="portrait.png"
  ...
  ```

  ```http GET Content (?disposition=attachment) theme={null}
  GET /lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9&disposition=inline HTTPS/2
  Host: example.ilucca.net
  Authorization: Bearer XXX

  > Response 200 OK
  Content-disposition: attachment; filename="portrait.png"
  ...
  ```
</CodeGroup>

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

<CodeGroup>
  ```http POST theme={null}
  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"
  }
  ```

  ```bash cURL (renaming on upload) theme={null}
  # The file on disk is a raw scanner output ("SKM_C25824011512.pdf"),
  # but it is stored under a meaningful name via the filename parameter.
  curl --location 'https://example.ilucca.net/lucca-api/files' \
  --header 'Authorization: Bearer XXX' \
  --form 'file=@"/scans/SKM_C25824011512.pdf";filename="employment-contract-john-doe.pdf"'

  # > Response 201 Created
  # {
  #     "id": "9b2c1e77-4d3a-4e21-8f0b-1c2d3e4f5a6b",
  #     "type": "file",
  #     "url": "https://example.ilucca.net/lucca-api/files/9b2c1e77-4d3a-4e21-8f0b-1c2d3e4f5a6b",
  #     "fileName": "employment-contract-john-doe.pdf",
  #     "contentType": "application/pdf",
  #     "size": 84213,
  #     "createdAt": "2024-01-15T10:20:30Z"
  # }
  ```
</CodeGroup>

<Tip>File names are sanitized on upload: the characters `< > [ ] { } " ' ; = |` and the backtick are replaced with an underscore (`_`).</Tip>