Read an upload ticket

GEThttps://<your-url>/api/v2/uploads/{upload}

MCP id uploads.showAlso on this path: DELETE Delete an upload ticket

Returns one of your own upload tickets: its status, the size and SHA-256 of the bytes the server actually received, the media type it detected from them, both deadlines and, while the ticket is still waiting for its bytes, the upload_url to PUT them to.

Token scope: api:read:project_managementorapi:read:project_driveorapi:read:customer_driveorapi:read:organization_driveorapi:read:user_drive
Without it: 403 insufficient-token-scope.
Permission: None. The record's own rules still apply.
Rate cost: 1 unit, read bucket.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Check whether an upload landed

curl -X GET \
  'https://<your-url>/api/v2/uploads/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/uploads/1', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/uploads/1');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/uploads/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "work_item_id": 1,
    "drive_item_id": 1,
    "collection": "…",
    "file_name": "…",
    "byte_size": 1,
    "checksum_sha256": "…",
    "received_byte_size": 1,
    "received_checksum_sha256": "…",
    "mime_type": "…",
    "status": "pending",
    "upload_url": "…"
  }
}

8 more fields, listed under Response

Use it to check whether an upload landed before registering it, or to recover the media_id of one already registered. A ticket belongs to the credential that created it: somebody else's ticket is 404, and so is one whose permission family your token does not cover. No domain permission is required (the ticket is your own scratch object), but the parent record's write permission was checked when it was created and is checked again when it is registered. Tickets are hard-deleted, so trashed is not an accepted parameter, and a pruned one is 404.

Path parameters

uploadintegerRequired

The Upload's numeric id.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a Upload in the detail view.

Headers

ETag: A strong validator of exactly this representation.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier. Send this as upload_id when you register the bytes.

work_item_idinteger or null

The work item this ticket attaches to, or null when it targets a drive item.

drive_item_idinteger or null

The drive item this ticket attaches to, or null when it targets a work item.

collectionstring≤ 255

The media collection the file will land in. Always attachments: it is chosen by the route, and no request field can change it.

file_namestring≤ 255

The sanitized file name the file will carry. Sent when the ticket is created; control characters are stripped and #, /, \ and spaces become hyphens, so what you read back can differ from what you sent.

byte_sizeinteger

The size you declared when creating the ticket. A declaration, not a bound: the server counts the bytes it actually receives.

checksum_sha256string or null

The optional SHA-256 you declared when creating the ticket. When present the server refuses bytes that do not match it.

received_byte_sizeinteger or null

The number of bytes that actually arrived, measured by the server. Null until the upload lands.

received_checksum_sha256string or null

The SHA-256 the server computed over the bytes it received. Null until the upload lands.

mime_typestring or null≤ 255

The media type detected from the received bytes. Detected, never declared: the API accepts no content type when creating the ticket and ignores the Content-Type of the upload itself.

statusstring

Where the ticket is in its lifecycle.

pendinguploadedcommittingcommittedexpiredrevoked

New values may be added.

upload_urlstring or null

Where to PUT the file. An opaque absolute URL: send the raw file as the body of a PUT whose only header is your Authorization bearer token. No Content-Type is read and the body is stored exactly as sent, so a form envelope would become part of the file. Present only while status is pending.

expires_attimestamp (YYYY-MM-DDThh:mm:ssZ)

The deadline for the PUT. After it the ticket is dead and a new one must be created.

register_bytimestamp (YYYY-MM-DDThh:mm:ssZ) or null

The deadline for the registration, set when the bytes land and measured from that moment, so a slow upload does not eat into the time you have to register. Null until the upload lands.

uploaded_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

When the bytes arrived. Null until they do.

committed_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

When the bytes became a file. Null until they do.

media_idinteger or null

The id of the file this ticket became. Null until it is registered, and set exactly once.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

When the ticket was created.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

linksUploadLinks

Show 1 child field