Start a file upload on a drive item

POSThttps://<your-url>/api/v2/drive-items/{drive_item}/uploads

MCP id drive-items.uploads.store

Step 1 of 3.

Token scope: api:write:project_driveorapi:write:customer_driveorapi:write:organization_driveorapi:write:user_drive
Without it: 403 insufficient-token-scope.
Permission: project_drive::create
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

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

Request

Example: Stage a report for a drive document

curl -X POST \
  'https://<your-url>/api/v2/drive-items/1/uploads' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "file_name": "quarterly-report.pdf",
    "byte_size": 184320
  }'

const response = await fetch('https://<your-url>/api/v2/drive-items/1/uploads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "file_name": "quarterly-report.pdf",
    "byte_size": 184320
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/drive-items/1/uploads', [
        'file_name' => 'quarterly-report.pdf',
        'byte_size' => 184320,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/drive-items/1/uploads',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'file_name': 'quarterly-report.pdf', 'byte_size': 184320},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "work_item_id": 1,
    "drive_item_id": 1,
    "collection": "…",
    "file_name": "quarterly-report.pdf",
    "byte_size": 184320,
    "checksum_sha256": "…",
    "received_byte_size": 1,
    "received_checksum_sha256": "…",
    "mime_type": "…",
    "status": "pending",
    "upload_url": "…"
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/state-conflict",
  "title": "State conflict",
  "status": 409,
  "detail": "The target status is not reachable from this work item's current status.",
  "instance": "/api/v2/work-items/812/actions/transition",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "conflict": {
    "reason": "illegal_transition",
    "from_workflow_status_id": 3,
    "to_workflow_status_id": 9
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

8 more fields, listed under Response

Returns an upload ticket whose upload_url you PUT the raw bytes to, after which you POST the ticket's id as upload_id to drive-items/{drive_item}/files to turn those bytes into a file. The bytes never travel through this API: /api/v2 accepts application/json and nothing else, so the upload target is a separate signed route. The file always lands in the document's attachments collection (content belongs to the editor and file is the document's own single payload, so neither is writable here), and the collection, the storage location and the ticket lifetime are all chosen by the server. The declared size is not a bound: the server counts what arrives and refuses anything over 10 MB. The declared permission is project_drive::create; customer_drive, organization_drive and user_drive apply by owner type, and the record rule requires edit access: read access to a document is not enough to attach to it, which is deliberately stricter than plnnrly. An archived document is 404. The ticket is yours alone, is single-use, expires in 30 minutes, and can be deleted with DELETE uploads/{upload} while unregistered.

Path parameters

drive_itemintegerRequired

The DriveItem's numeric id. Accepts a soft-deleted record.

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.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

file_namestring≤ 255Required

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_sizeinteger1 to 10485760Required

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≤ 64

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

sha-256 hex digest

Response 201

Returns a Upload in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
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

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