Post element file endpoint

post /<uuid>/file

Post element file

Uploads a file to the referenced element. Fails with 409 Conflict if the element already has a file attached - use PUT /<uuid>/file to replace an existing file instead.

The endpoint supports two upload modes, selected through the Upload-Complete request header:

Direct upload - Upload-Complete: ?1, or the header omitted entirely. The request body is the complete file. On success, the endpoint responds with 201 Created and no body.
Resumable upload - Upload-Complete: ?0. Starts a resumable upload instead of attaching a file right away; any data sent in this first request is stored as the upload’s first chunk. On success, the endpoint responds with 204 No Content, and a Location header pointing at the new resumable upload’s URL under /upload/<uuid>. Continue it with PATCH /upload/<uuid>, inspect it with HEAD /upload/<uuid>, or abort it with DELETE /upload/<uuid>.

Both modes use the same request headers:

Content-Disposition: attachment; filename="<name>" (optional) - determines the file’s extension, which is stored and later used to reconstruct the Content-Disposition header on GET /<uuid>/file. Falls back to bin if omitted, or if no extension can be parsed from the filename.
Upload-Length (optional, resumable uploads only) - total size in bytes of the finished file, once all chunks have been appended.

Resumable uploads follow the IETF draft, not tus.io

The header names (Upload-Offset, Upload-Length, Upload-Complete, Upload-Limit) come from the IETF “resumable uploads for HTTP” draft, not the older tus.io protocol - there is no Tus-Resumable header, and Upload-Complete uses the structured boolean values ?0/?1 rather than a plain string.

Whenever a resumable upload is created (or continued via PATCH /upload/<uuid>), the response includes an Upload-Limit header describing the current server limits: how long an unfinished upload is kept alive, the maximum total file size, and the minimum and maximum size of an individual chunk. A chunk smaller than the minimum is rejected with 400 Bad Request, unless it is the upload’s last chunk (Upload-Complete: ?1) or has zero length. A direct upload’s 201 Created response carries none of these headers, since there is no ongoing upload to describe.

Since a zero-length chunk is always accepted, Upload-Complete: ?0 with an empty body can be used purely to create the resumable upload and read back its Upload-Limit, before deciding on a chunking strategy.

Verifying upload integrity

A direct upload (Upload-Complete: ?1, or the header omitted) can optionally carry a Repr-Digest header with the SHA-256 digest of the file, in RFC 9530 structured-field format (sha-256=:[base64]:). Once the upload finishes, the server recomputes the digest and compares it; a mismatch fails with 400 Bad Request and the file is not stored. Content-Digest is accepted as a fallback header name.

This only verifies a direct upload’s complete body. For a resumable upload, send the digest on the completing PATCH /upload/<uuid> request instead, once the full file has been reassembled server-side.

Request

Create file directly

curl \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/octet-stream' \
  -H 'Content-Disposition: attachment; filename="report.pdf"' \
  --data-binary @report.pdf \
  https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file

import requests

url = "https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file"

payload = "@report.pdf"
headers = {
  "Authorization": "Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc",
  "Content-Type": "application/octet-stream",
  "Content-Disposition": "attachment; filename=\"report.pdf\""
}

response = requests.post(url, data=payload, headers=headers)

print(response.json())

const url = 'https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Type': 'application/octet-stream',
    'Content-Disposition': 'attachment; filename="report.pdf"'
  },
  body: '@report.pdf'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file', [
  'body' => '@report.pdf',
  'headers' => [
    'Authorization' => 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Disposition' => 'attachment; filename="report.pdf"',
    'Content-Type' => 'application/octet-stream',
  ],
]);

echo $response->getBody();

Create resumable upload

curl \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/octet-stream' \
  -H 'Content-Disposition: attachment; filename="report.pdf"' \
  -H 'Upload-Complete: ?0' \
  -H 'Upload-Length: 20971520' \
  --data-binary @report.pdf.part1 \
  https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file

import requests

url = "https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file"

payload = "@report.pdf.part1"
headers = {
  "Authorization": "Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc",
  "Content-Type": "application/octet-stream",
  "Content-Disposition": "attachment; filename=\"report.pdf\"",
  "Upload-Complete": "?0",
  "Upload-Length": "20971520"
}

response = requests.post(url, data=payload, headers=headers)

print(response.json())

const url = 'https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Type': 'application/octet-stream',
    'Content-Disposition': 'attachment; filename="report.pdf"',
    'Upload-Complete': '?0',
    'Upload-Length': '20971520'
  },
  body: '@report.pdf.part1'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file', [
  'body' => '@report.pdf.part1',
  'headers' => [
    'Authorization' => 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Disposition' => 'attachment; filename="report.pdf"',
    'Content-Type' => 'application/octet-stream',
    'Upload-Complete' => '?0',
    'Upload-Length' => '20971520',
  ],
]);

echo $response->getBody();

Response

201 · Created

The complete file was uploaded directly (Upload-Complete: ?1, or the header was omitted) and is now attached to the element. Returned without a response body.

Verifying upload integrity

Request

Response

Request Parameters

Request Header

Request Body

Response Header