head /upload/<uuid>

Head upload

Returns the current state of a resumable upload created by POST /<uuid>/file or PUT /<uuid>/file, without transferring any of the data already uploaded. The response has no body - Upload-Offset, Upload-Length, Upload-Complete, Upload-Limit and Expires are all returned as headers, matching what the creating request or the last PATCH /upload/<uuid> returned.

Only the user who created the upload can query it - even a user with full access to the upload’s target element gets 404 for an upload they did not start themselves.

This endpoint does not support If-Match or If-None-Match; unlike the element endpoints, requesting it with either header has no effect.

Request

curl -I \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  https://api.example.com/upload/74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac
import requests


url = "https://api.example.com/upload/74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac"


headers = {"Authorization": "Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc"}


response = requests.head(url, headers=headers)


print(response.json())
const url = 'https://api.example.com/upload/74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac';
const options = {
  method: 'HEAD',
  headers: {Authorization: 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc'}
};


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('HEAD', 'https://api.example.com/upload/74a8fcd9-6cb0-4b0d-8d42-0b6c3c54d1ac', [
  'headers' => [
    'Authorization' => 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
  ],
]);


echo $response->getBody();

Response

204 · No Content

Resumable upload found. Its current state is returned entirely through response headers - there is no response body.

MDN HTTP.dev 

401 · Unauthorized

The provided token is either invalid or expired.

MDN HTTP.dev 

404 · Not Found

No resumable upload with this id exists, it already expired or completed, or it belongs to a different user.

MDN HTTP.dev 

response has no body

Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
Upload-Complete: ?0
Upload-Offset: 5242880
Upload-Length: 20971520
Upload-Limit: max-age=10800, max-size=10737418240, min-append-size=5242880, max-append-size=105906176
Expires: Sat, 22 Aug 2026 21:22:07 GMT
X-Powered-By: Ember Nexus API

no schema available

{
  "type": "https://api.example.com/error/401/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization for the request failed due to possible problems with the token (incorrect or expired), password (incorrect or changed), the user's unique identifier, or the user's status (e.g., missing, blocked, or deleted)."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
{
  "type": "https://api.example.com/error/404/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Requested element was not found."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}

Request Parameters

uuid

required

pathstringuuid

Id of the resumable upload, as returned in the Location header of the request that created it.

Request Header

Authorization

optional

Bearer token for user authentication. If omitted, the request is processed as an anonymous user; if provided, the associated user account is used.

MDN HTTP.dev Authentication guide 

Response Header

Upload-Complete

always

Structured boolean indicating whether the upload is finished: ?1 for complete, ?0 for still in progress.

IETF draft HTTP.dev 

Upload-Offset

always

Number of bytes already stored for the resumable upload. On a request, it must match the upload's current offset exactly; on a response, it reflects the offset after the request was processed.

IETF draft HTTP.dev 

Upload-Length

optional

Total number of bytes the finished file will have. Optional - omitted when the total size is not known ahead of time.

IETF draft HTTP.dev 

Upload-Limit

always

Structured field listing the server's limits for this upload: max-age (seconds an unfinished upload is kept alive since its first request), max-size (maximum total file size in bytes), min-append-size (minimum size in bytes for a non-final chunk) and max-append-size (maximum size in bytes per chunk).

IETF draft HTTP.dev 

Expires

always

Point in time after which the unfinished resumable upload is discarded, if it is not completed before then.

MDN HTTP.dev 

Access-Control-Allow-Headers

always

Specifies which HTTP headers can be used during a cross-origin request, returned in preflight responses.

MDN HTTP.dev 

Access-Control-Allow-Methods

always

Indicates which HTTP methods are permitted for cross-origin requests, typically returned in preflight responses.

MDN HTTP.dev 

Access-Control-Allow-Origin

always

Specifies which origin(s) may access the resource.

MDN HTTP.dev 

Access-Control-Expose-Headers

always

Lists the response headers that browsers are allowed to access from JavaScript beyond the default restricted set.

MDN HTTP.dev 

Allow

always

Lists the HTTP methods supported by the endpoint; returned alongside a 405 Method Not Allowed response.

MDN HTTP.dev 

Cache-Control

always

Directives controlling caching behavior for the response.

MDN HTTP.dev 

X-Powered-By

always

Identifies the underlying API implementation.

MDN HTTP.dev