Getting started with the API

Create an API key, then upload images, create QRs, and run optimizations via REST

Uppic exposes a REST API under /api/v1 for uploading and managing images, creating QR codes, and running optimization jobs from your own systems.

Authentication

  1. 1Go to Dashboard → API Keys and create a key, choosing the scopes you need (e.g. images:write)
  2. 2Copy the key (it starts with upk_) immediately — it is shown in full only once
  3. 3Send it in the header of every request
Required header
Authorization: Bearer upk_YOUR_API_KEY
Note: Rate limits by plan: Free 100 · Pro 2,000 · Business 10,000 requests/hour — exceeding them returns HTTP 429.

Upload an image

POST /api/v1/images/upload (requires images:write)
curl -X POST https://uppic.example/api/v1/images/upload \
  -H "Authorization: Bearer upk_YOUR_API_KEY" \
  -F "files=@photo.jpg" \
  -F "expiresIn=never" \
  -F "privacy=UNLISTED" \
  -F "stripExif=true"
Sample response (201)
{
  "results": [
    {
      "id": "aB3xY9…",
      "links": {
        "sharePage": "https://uppic.example/image/photo.aB3xY9…",
        "direct": "https://uppic.example/f/photo.jpg",
        "thumbnail": "https://uppic.example/f/photo.th.jpg",
        "medium": "https://uppic.example/f/photo.md.jpg"
      },
      "embed": { "html": "…", "markdown": "…", "bbcode": "…" },
      "fileName": "photo.jpg",
      "fileSize": 123456,
      "width": 1920,
      "height": 1080
    }
  ]
}

Other accepted fields: title, sourceUrl (upload by URL), galleryId (attach to a gallery), plus optimize/outputFormat/quality/maxWidth for compress-before-host.

Create a QR code

POST /api/v1/qr-codes (requires qr:write)
curl -X POST https://uppic.example/api/v1/qr-codes \
  -H "Authorization: Bearer upk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campaign QR",
    "mode": "DYNAMIC",
    "data": { "type": "url", "url": "https://example.com/landing" }
  }'
Edit a dynamic QR destination later
curl -X PATCH https://uppic.example/api/v1/qr-codes/QR_ID \
  -H "Authorization: Bearer upk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destinationUrl": "https://example.com/new-landing" }'

Run an optimization job

POST /api/v1/optimizations (requires optimize:write)
# Submit a job (up to 20 files depending on plan)
curl -X POST https://uppic.example/api/v1/optimizations \
  -H "Authorization: Bearer upk_YOUR_API_KEY" \
  -F "files=@photo.png" -F "format=webp" -F "quality=80"

# Poll job status
curl https://uppic.example/api/v1/optimizations/JOB_ID \
  -H "Authorization: Bearer upk_YOUR_API_KEY"

# Download all results as a ZIP when done
curl -L https://uppic.example/api/v1/optimizations/JOB_ID/download \
  -H "Authorization: Bearer upk_YOUR_API_KEY" -o results.zip
Tip: Want to know the moment a job finishes without polling? Set up webhooks for the optimization.completed event — see the Webhooks article next.
Was this article helpful?

Related articles

Still need help?

The team is happy to answer your questions directly

Contact us