Skip to main content
Text promotions skip this step entirely. If your content is plain text or HTML, provide it inline via the content field when creating a promotion.Reviewing a web page or Figma frame? You don’t need a file. Submit the URL via Link submission and Adclear captures it for you.
Uploads use a resumable chunked protocol. You initiate the upload, then send the file in one or more chunks using Content-Range headers.
1

Initiate the upload

Request:
Response:
  • uploadUrl is the relative path for chunk uploads.
  • maxChunkSize is the maximum bytes per chunk (default 50 MB). The final chunk may be smaller.
2

Upload the file in chunks

Send the file bytes as one or more PUT requests with a Content-Range header.
Content-Range format: bytes <start>-<end>/<total>, where start and end are zero-based inclusive byte offsets and total is the full file size. For a multi-chunk upload, repeat with the next byte range until the response status is completed.
3

Check upload status (optional)

You can poll upload status at any time:
Status transitions: pendinguploadingcompleted | failed.

Full upload example

The curl tab covers the single-chunk happy path. The TypeScript and Python tabs handle chunking for large files.

Implementation notes

  • A promotion references exactly one upload. To review several files, create a separate promotion for each.
  • If a chunk fails due to a network error, check the upload status to see how many bytes were received, then resume from that offset.
  • Uploading to an already-completed upload returns 409 Conflict.

Common error scenarios

For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.

Frequently asked questions

No. A promotion references exactly one upload. To review several files, create a separate promotion for each.
Yes. Upload IDs aren’t consumed. The same upload can be referenced by multiple promotions or versions.
Completed uploads are stored indefinitely. If you initiate an upload and never send any chunks, the upload session may eventually become unusable, so complete uploads promptly after initiation.