Upload24 API docs

Video upload endpoints, authentication, and request flow

This page documents the practical upload API: how to create a key, which header to send, which endpoint to call for each upload strategy, and what constraints matter in production.

QuickstartAuthenticationEndpointsExamples

Quickstart

If you only need the shortest path to a working integration, follow these three steps first and use the endpoint reference after that.

Step 1

Create an API key in the dashboard

API keys are generated through a bearer-authenticated dashboard session. The returned key is only shown once, so store it immediately.

Step 2

Send X-Api-Key on upload requests

Upload creation, completion, abort, and status endpoints accept the raw API key in the X-Api-Key header. Do not prefix it with Bearer.

Step 3

Pick the upload flow that matches your infrastructure

Use presign-put for direct object uploads, or multipart presigning for larger files and resumable transfer.

Authentication model

Key management is protected by bearer authentication, while upload execution accepts either bearer auth or the raw API key. The upload-specific header is X-Api-Key and should contain the full key string with no prefix.

Operational note: Upload requests only work when the target accounts are already linked to the current tenant. API keys do not replace the account linking step in the dashboard.
Create a key
curl -X POST "$BASE_URL/api-keys/generate" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI uploads" }'
Use the returned key on upload requests
curl -X GET "$BASE_URL/api/upload/$UPLOAD_ID/status" \
  -H "X-Api-Key: $API_KEY"

Endpoint reference

These are the routes that matter for end-to-end upload automation. The table focuses on the auth mode, payload type, and the job each endpoint performs.

POST/api-keys/generate

Generate API key

Creates a new key for the current tenant. Request body supports an optional name field. The full key is returned only in this response.

Auth
Bearer JWT
Request
application/json
POST/api/upload/presign-put

Create single-put upload session

Returns a session token, file id, and direct upload URL. After uploading the object, finish the flow with /api/upload/complete.

Auth
X-Api-Key or Bearer JWT
Request
application/json
POST/api/upload/multipart

Create multipart upload session

Returns presigned URLs for each part together with the session token. Use it when large files or unstable networks make chunked transfer safer.

Auth
X-Api-Key or Bearer JWT
Request
application/json
POST/api/upload/complete

Complete upload session

Finalizes either the single-put or multipart flow and creates the actual upload record that starts processing against target accounts.

Auth
X-Api-Key or Bearer JWT
Request
application/json
POST/api/upload/abort

Abort upload session

Cancels an unfinished upload session and removes the staged object when possible.

Auth
X-Api-Key or Bearer JWT
Request
application/json
GET/api/upload/{uploadId}/status

Fetch upload status

Returns aggregate status plus per-account delivery details, including external ids and failure information when available.

Auth
X-Api-Key or Bearer JWT
Request
No body
GET/uploads

List tenant uploads

Dashboard-focused endpoint for paginated upload history. It is not exposed through API key auth.

Auth
Bearer JWT only
Request
Query params

Validation rules and limits to model in your client

  • Files must be larger than 0 bytes and no more than 2 GB.
  • Every upload needs at least one linked account that belongs to the current tenant.
  • The title field is required and capped at 2200 characters.
  • Scheduled posts cannot be placed more than one year into the future.
  • Quota is charged per target account, not per API request.
  • When you include YouTube metadata, categoryId, defaultLanguage, and defaultAudioLanguage become mandatory.

Public status meanings

Scheduled

The upload record is accepted and waiting for its scheduled dispatch window.

Processing

The upload is actively being dispatched or retried. Internal Retrying and Dispatching states are both presented as Processing.

Uploaded

The target platform confirmed publication for the account entry.

Failed

The upload could not be completed for at least one destination. Check per-account errorCode and errorMessage values.

Request examples

Use these examples as starting points. Replace the placeholders with your actual base URL, bearer token, API key, account ids, and file paths.

Presigned single-put flow
curl -X POST "$BASE_URL/api/upload/presign-put" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Spring launch teaser",
    "accounts": ["account_123"],
    "fileName": "video.mp4",
    "fileSize": 734003200,
    "contentType": "video/mp4"
  }'

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @./video.mp4

curl -X POST "$BASE_URL/api/upload/complete" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessionToken": "$SESSION_TOKEN", "parts": [] }'

Want the architectural overview too?

The first Upload24 blog article explains why the API is split into key management, upload session creation, and per-account delivery tracking.

Read the articleOpen dashboard