The file object

• object string: "file"

• id uuid

• itemId uuid: The item or collection the file is attached to.

• fileName string

• url string: The URL of the file, which is how item content references the file

• createdAt date

• createdUserId uuid

• download object

  • url string: Download URL to the file which is valid for 10 minutes.

  • expiresAt date

Get file

Endpoint: GET /v0/files/:id

Example request

curl https://api.nuclino.com/v0/files/eec0a152-b1e9-43fd-bef8-987f95c85c6e \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "status": "success",
  "data": {
    "object": "file",
    "id": "eec0a152-b1e9-43fd-bef8-987f95c85c6e",
    "itemId": "dd9a69db-048d-4644-8738-36bee31bbee0",
    "fileName": "screenshot.png",
    "url": "https://files.nuclino.com/files/eec0a152-b1e9-43fd-bef8-987f95c85c6e/screenshot.png",
    "createdAt": "2021-12-15T07:58:11.196Z",
    "createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
    "download": {
      "url": "https://nuclino-files.s3.eu-central-1.amazonaws.com/a122ab11...",
      "expiresAt": "2021-12-15T08:08:49.931Z"
    }
  }
}

Upload file

Endpoint: POST /v0/files

Uploads a file and attaches it to an item or collection. Requires edit access to the item. The file counts towards the storage of the team and is processed after the upload.

The file can either be sent with the request (multipart upload) or downloaded from a URL. Both are limited to files of up to 10 MB. For larger files, use a direct upload as described below.

Multipart upload

Send the request as multipart/form-data with these form fields:

• file file: The file to upload. Required.

• itemId uuid: The item or collection to attach the file to. Required.

• fileName string: A file name that overrides the name of the uploaded file. Optional.

Example request

curl https://api.nuclino.com/v0/files \
  -H "Authorization: YOUR_API_KEY" \
  -F "itemId=dd9a69db-048d-4644-8738-36bee31bbee0" \
  -F "file=@screenshot.png"

Upload from a URL

Send the request as JSON to let Nuclino download the file:

• itemId uuid: The item or collection to attach the file to. Required.

• url string: A publicly accessible http(s) URL of the file. Required.

• fileName string: A file name that overrides the name derived from the response or the URL. Optional.

Example request

curl https://api.nuclino.com/v0/files \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "dd9a69db-048d-4644-8738-36bee31bbee0",
    "url": "https://example.com/reports/report.pdf"
  }'

Example response

Both variants respond with the created file object:

{
  "status": "success",
  "data": {
    "object": "file",
    "id": "eec0a152-b1e9-43fd-bef8-987f95c85c6e",
    "itemId": "dd9a69db-048d-4644-8738-36bee31bbee0",
    "fileName": "screenshot.png",
    "url": "https://files.nuclino.com/files/eec0a152-b1e9-43fd-bef8-987f95c85c6e/screenshot.png",
    "createdAt": "2021-12-15T07:58:11.196Z",
    "createdUserId": "2e96f3bb-c742-4164-af2c-151ab2fd346b",
    "download": {
      "url": "https://nuclino-files.s3.eu-central-1.amazonaws.com/a122ab11...",
      "expiresAt": "2021-12-15T08:08:49.931Z"
    }
  }
}

Errors

Direct upload

For files larger than 10 MB, upload the file directly to the file storage of Nuclino in three steps:

1. Create an upload, which returns the upload URL and form fields for the file storage.

2. Send the file to the file storage.

3. Complete the upload, which attaches the file to the item.

The fileUpload object

• object string: "fileUpload"

• id uuid: The ID of the upload.

• itemId uuid

• fileName string

• contentType string

• contentLength number: The size of the file in bytes.

• upload object

  • method string: "POST"

  • url string: The URL of the file storage to send the file to.

  • fields object: Form fields that have to be sent along with the file.

  • expiresAt date: The file has to be sent before this date.

Create upload

Endpoint: POST /v0/files/uploads

Requires edit access to the item. Body parameters:

• itemId uuid: The item or collection to attach the file to. Required.

• fileName string: The name of the file including the extension. Required.

• contentLength number: The exact size of the file in bytes. Required.

• contentType string: The MIME type of the file. Optional, derived from the file name by default.

Example request

curl https://api.nuclino.com/v0/files/uploads \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "dd9a69db-048d-4644-8738-36bee31bbee0",
    "fileName": "recording.mp4",
    "contentLength": 52428800,
    "contentType": "video/mp4"
  }'

Example response

{
  "status": "success",
  "data": {
    "object": "fileUpload",
    "id": "3f0b6a7e-9c2d-4e8f-b1a5-6d7c8e9f0a1b",
    "itemId": "dd9a69db-048d-4644-8738-36bee31bbee0",
    "fileName": "recording.mp4",
    "contentType": "video/mp4",
    "contentLength": 52428800,
    "upload": {
      "method": "POST",
      "url": "https://nuclino-files.s3.eu-central-1.amazonaws.com/",
      "fields": {
        "bucket": "nuclino-files",
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "AKIA.../20260921/eu-central-1/s3/aws4_request",
        "X-Amz-Date": "20260921T120000Z",
        "key": "6d7c8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f/recording.mp4",
        "Policy": "eyJleHBpcmF0aW9uIjoi...",
        "X-Amz-Signature": "a1b2c3d4...",
        "Content-Type": "video/mp4"
      },
      "expiresAt": "2026-09-21T18:00:00.000Z"
    }
  }
}

Send the file

Send a multipart/form-data POST request to upload.url that contains every entry of upload.fields as a form field, followed by the file as the last field named file. The content type and the size of the file must match the values the upload was created with. The file storage responds with a 204 status on success.

Example request

curl -X POST "https://nuclino-files.s3.eu-central-1.amazonaws.com/" \
  --form-string "bucket=nuclino-files" \
  --form-string "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  --form-string "X-Amz-Credential=AKIA.../20260921/eu-central-1/s3/aws4_request" \
  --form-string "X-Amz-Date=20260921T120000Z" \
  --form-string "key=6d7c8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f/recording.mp4" \
  --form-string "Policy=eyJleHBpcmF0aW9uIjoi..." \
  --form-string "X-Amz-Signature=a1b2c3d4..." \
  --form-string "Content-Type=video/mp4" \
  -F "file=@recording.mp4"

Complete upload

Endpoint: POST /v0/files/uploads/:id/complete

Verifies that the file was sent to the file storage, attaches it to the item and starts processing it. Responds with the created file object. Completing the same upload again returns the same file. Uploads that are never completed are discarded.

Body parameters:

• itemId uuid: The item or collection the upload was created for. Required.

Example request

curl https://api.nuclino.com/v0/files/uploads/3f0b6a7e-9c2d-4e8f-b1a5-6d7c8e9f0a1b/complete \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemId": "dd9a69db-048d-4644-8738-36bee31bbee0"}'

Errors