upload.ad documentation

upload.ad is a bulk uploader for Meta (Facebook/Instagram) and TikTok ad creatives. You send images and videos to upload.ad, it pushes them to your ad account's media library, and it stores ad copy variants alongside each creative so your launch tooling has everything in one place.

There are three ways to integrate. They all use the same API keys and expose the same data:

REST API: a plain HTTPS API for scripts and backend services. Full endpoint reference with curl and JavaScript examples.
CLI: the uploadad command for terminals and CI pipelines.
MCP server: lets AI agents such as Claude Code, Claude Desktop, and Cursor manage creatives and copy on your behalf.

Quickstart

This walkthrough uploads a creative with curl and polls it to completion. It takes about two minutes.

1. Create an API key

Create a key at upload.ad/dashboard/settings/api-keys. The key is shown once at creation, so store it securely. Then export it in your shell:

bash

export UPLOADAD_API_KEY="ua_live_..."

2. Upload a creative

Send one or more files as multipart/form-data:

bash

curl -X POST https://upload.ad/api/v1/uploads \
  -H "Authorization: Bearer $UPLOADAD_API_KEY" \
  -F "files=@banner.png"

The response returns immediately with an upload id. Processing happens in the background:

json

{ "uploads": [{ "id": "up_1", "status": "processing" }] }

3. Poll until it finishes

Fetch the upload until its status is completed or failed:

bash

curl https://upload.ad/api/v1/uploads/up_1 \
  -H "Authorization: Bearer $UPLOADAD_API_KEY"

json

{
	"upload": {
		"id": "up_1",
		"fileName": "banner.png",
		"kind": "image",
		"status": "completed",
		"facebook": { "imageHash": "a1b2c3...", "videoId": null },
		"createdAt": "2026-07-09T10:15:00.000Z"
	}
}

A completed image upload carries the Graph API imageHash, and a completed video upload carries the videoId. Both are ready to reference when you create ads through the Graph API.

4. Attach ad copy

Once processing completes, the file appears in your creative library. List creatives to find its id, then save a copy variant:

bash

curl -X POST https://upload.ad/api/v1/creatives/cr_1/copy \
  -H "Authorization: Bearer $UPLOADAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "headline": "Summer sale", "primaryText": "Save 20% this week only.", "label": "variant-a" }'

From here, the REST API reference covers every endpoint, or you can do the same from the terminal with the CLI.

Authentication

Every request is authenticated with an API key sent as a Bearer token:

Authorization: Bearer ua_live_...

Keys are created and revoked at upload.ad/dashboard/settings/api-keys. Requests with a missing or invalid key return 401 with a JSON error body. Treat keys like passwords: keep them out of source control and pass them through environment variables or a secret manager.

Base URL and format

The base URL for all endpoints is https://upload.ad. Requests and responses are JSON, except file uploads, which use multipart/form-data. Errors return a 4xx or 5xx status with a body of the form:

json

{ "message": "Description of the problem" }