Skip to main content
GET
/
lucca-api
/
files
/
{id}
Retrieve a file
curl --request GET \
  --url https://{host}/lucca-api/files/{id} \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'
{
  "id": "2face165-5345-4cf3-ab05-5421a6b19df2",
  "type": "file",
  "url": "https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2",
  "fileName": "pic.jpg",
  "contentType": "image/jpg",
  "createdAt": "2024-01-15T08:30:00Z",
  "links": {},
  "embedded": {}
}

Authorizations

​
Authorization
string
header
required

The Lucca API implements the oAuth 2 protocol with the client-credentials-flow. Refer to RFC8725.

Headers

​
Accept
string

The Accept response header indicates the content type of the response.

  • Accept: application/octet-stream returns the raw file content.
  • Accept: images/* returns a preview of the file (when possible).
  • If Accept matches exactly file.contentType, returns the raw file content.
  • Accept: application/json or Accept: */* or no Accept header (default) returns the file metadata in JSON format.
​
Api-Version
enum<string>
required

Set the API version.

Available options:
2024-11-01
Allowed value: "2024-11-01"
Maximum string length: 10
Example:

"2024-11-01"

​
If-None-Match
string

Only execute the request if current cached version of the resource does not match the one given here.

Example:

"W/q5sd4w2x1c1gfdg"

​
If-Match
string

Only execute the request if current cached version of the resource matches the one given here. Useful to avoid concurrency conflicts.

Example:

"W/q5sd4w2x1c1gfdg"

​
Accept-Encoding
string

List of compression algorithms you support.

Path Parameters

​
id
string<uuid>
required

Unique id of the file.

Query Parameters

​
token
string
required

The token allowing to access the file. This token can only be obtained via the links of the API resource that references this file.

Minimum string length: 1
​
disposition
enum<string>

Specifies how the file should be handled by the client.

Supersedes the Accept header when possible. To be used whenever the API client cannot set custom Accept headers.

  • json (default) returns the file metadata in JSON format.
  • inline returns the file content to be displayed inline in the browser (when possible).
  • attachment returns the file content as a download.
Available options:
json,
inline,
attachment
​
include
enum<string>[]

Include metadata:

  • embedded: the partial or complete representations of related resources (e.g. the employee the resource belongs to).
  • links: links to related resources or actions (e.g. approving a leave-request). May be null when you do not have access to the resource (or action).
  • totalCount: only applicable on collections (i.e. lists of resources), gives the total number of items across all pages.

Read more about expanding responses.

Available options:
embedded,
links,
totalCount

Response

Representation of the requested file, either its JSON representation or its content.

JSON representation of a file. A file may be downloaded via the Accept: octet-stream HTTP header.

​
id
string
Minimum string length: 1
​
type
string
Allowed value: "file"
​
url
string<uri>
​
fileName
string
Minimum string length: 1
​
contentType
enum<string>

Indicates the content-type of the file. Refer to the enum values to figure out which are accepted.

Available options:
message/rfc822,
binary/octet-stream,
unknown/unknown,
audio/mpeg,
video/mp4,
image/png,
image/heic,
image/heif,
image/jpe,
image/jpg,
image/pjpeg,
image/gif,
image/bmp,
image/tif,
image/tiff,
image/x-dcraw,
image/x-jb2,
image/x-jbig2,
image/x-jpf,
image/x-ms-bmp,
image/x-panasonic-raw,
image/x-pcx,
image/x-icon,
image/x-png,
image/vnd.microsoft.icon,
image/webp,
image/svg+xml,
image/x-portable-anymap,
text/plain,
text/csv,
text/rtf,
text/calendar,
text/comma-separated-values,
text/css,
text/html,
text/xml,
text/markdown,
text/x-affix,
application/pdf,
application/msword,
application/xls,
application/x-csv,
application/ms-excel,
application/vnd.ms-office,
application/vnd.ms-word,
application/vnd.ms-outlook,
application/vnd.ms-powerpoint,
application/vnd.ms-excel,
application/vnd.ms-excel.sheet.binary.macroEnabled.12,
application/vnd.ms-excel.sheet.macroEnabled.12,
application/vnd.ms-pki.stl,
application/vnd.ms-xpsdocument,
application/vnd.oasis.opendocument.text,
application/vnd.oasis.opendocument.spreadsheet,
application/vnd.oasis.opendocument.presentation,
application/vnd.oasis.opendocument.graphics,
application/vnd.openxmlformats-officedocument.wordprocessingml.document,
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,
application/vnd.openxmlformats-officedocument.presentationml.presentation,
application/vnd.openxmlformats-officedocument.presentationml.slideshow,
application/vnd.openxmlformats-officedocument.presentationml.template,
application/x-7z-compressed,
application/rar,
application/x-rar,
application/zip,
application/andrew-inset,
application/binary,
application/csv,
application/download,
application/force-download,
application/x-download,
application/hta,
application/javascript,
application/json,
application/mac-binhex40,
application/oleobject,
application/pkcs7-signature,
application/postscript,
application/rtf,
application/text,
application/txt,
application/unknown,
application/x-iwork-keynote-sffkey,
application/x-ms-application,
application/x-ms-manifest,
application/x-msdownload,
application/x-pdf,
application/x-unknown,
application/x-zip-compressed,
application/xml,
application/x-wine-extension-ini,
application/vnd.hp-hpgl,
application/x-sega-pico-rom
​
createdAt
string<date-time-offset>

Read-only. UTC timestamp of the moment this object was created.

Example:

"2023-01-23T12:45:23.1234Z"

​
links
object
​
embedded
file.embedded · object

Embedded resources for a file.