Put element file endpoint

put /<uuid>/file

Put element file

Behaves exactly like POST /<uuid>/file - the same Upload-Complete, Upload-Length, Content-Disposition and Repr-Digest headers select between a direct upload (201 Created) and a resumable upload (204 No Content with a Location header), verify upload integrity, and the same Upload-Limit rules apply to chunk sizes.

The only difference is that this endpoint does not require the element to be empty: if it already has a file attached, that file is replaced once the (possibly resumable) upload completes - including replacing it with a file of a different extension, e.g. overwriting a .jpg with a .txt. The old file is removed from storage as part of the replacement.

Because a replacement is destructive, this endpoint supports If-Match against the current file’s ETag, letting concurrent writers detect that the file changed since it was last read. POST has no such check, since it can only ever create a file, never overwrite one.

If a Repr-Digest (or Content-Digest) sent with the upload does not match the uploaded content, the request fails with 400 Bad Request and the existing file is left untouched - a failed replacement never leaves the element without a file, or with a partially-written one.

Request

Create file directly

curl -X PUT \
  -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.put(url, data=payload, headers=headers)

print(response.json())

const url = 'https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file';
const options = {
  method: 'PUT',
  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('PUT', '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 -X PUT \
  -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.put(url, data=payload, headers=headers)

print(response.json())

const url = 'https://api.example.com/7b80b203-2b82-40f5-accd-c7089fe6114e/file';
const options = {
  method: 'PUT',
  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('PUT', '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, replacing any previous file. Returned without a response body.

Request

Response

Request Parameters

Request Header

Request Body

Response Header