How to Use the dbimg API to Automate Image Uploads

Automate Image Uploads With the dbimg API

If you upload images more than occasionally, you should not be doing it by hand. The dbimg API turns any upload into a single HTTP request you can wire into scripts, apps, screenshot tools, and CI pipelines. This guide covers everything needed to go from zero to your first automated upload.

Step 1: Get Your API Key

Create a free dbimg account, then generate an API key from your dashboard. Keys look like dbimg_xxxxxxxx and authenticate with a standard bearer header:

Authorization: Bearer dbimg_xxxxxxxx

One deliberate design note: uploads through the website never need a key — anonymity is a feature. Programmatic access requires a key so abuse can be rate-limited fairly and your uploads land in your account where you can manage them.

Step 2: Your First Automated Upload

The entire API is one endpoint. To upload a file:

curl -X POST https://dbimg.app/api/upload \
  -H "Authorization: Bearer dbimg_xxxxxxxx" \
  -F "file=@photo.jpg"

The response is JSON describing your new upload:

{
  "id": "img_a1b2c3",
  "shortId": "abc123",
  "mediaUrl": "https://cdn.dbimg.app/abc123.jpg",
  "shareUrl": "/abc123",
  "deletionUrl": "/api/image/delete/TOKEN",
  "fileName": "photo.jpg",
  "fileSize": 482113,
  "mimeType": "image/jpeg",
  "hasPassword": false,
  "expiresAt": null,
  "maxViews": null
}

The three fields you will use most: mediaUrl is the permanent direct link, shareUrl is the human-friendly page, and deletionUrl lets your script delete the file later without an account login.

Step 3: Useful Parameters

All parameters are optional multipart form fields:

• password — protect the upload; visitors must enter it on the share page.
• expiresIn — auto-expire the file, e.g. 1w for one week.
• maxViews — self-destruct after N views.
• customSlug — pick your own link, e.g. -F "customSlug=release-banner" for a memorable URL.

Example combining several:

curl -X POST https://dbimg.app/api/upload \
  -H "Authorization: Bearer dbimg_xxxxxxxx" \
  -F "file=@build-log.png" \
  -F "expiresIn=1w" \
  -F "maxViews=10"

Rate Limits and Error Handling

Limits are generous but real: authenticated uploads allow 30 requests per minute, anonymous web uploads 10 per minute. When the server is genuinely overloaded you will receive 503 with a Retry-After header — honour it and retry with exponential backoff. Validation problems (bad format, blocked slug text) return 400 with a descriptive error field. A production integration needs roughly four lines of handling: check status, read Retry-After on 503, back off, log the error field on 4xx.

Automation Recipes

ShareX screenshot hotkeys (Windows)

Point a Custom HTTP Upload at https://dbimg.app/api/upload with your bearer header and the URL lands on your clipboard seconds after every capture. Full setup in our ShareX guide.

Folder-watcher script (Python)

import time, requests
from pathlib import Path

WATCH = Path("~/Screenshots").expanduser()
HEADERS = {"Authorization": "Bearer dbimg_xxxxxxxx"}

for f in WATCH.glob("*.png"):
    r = requests.post("https://dbimg.app/api/upload",
                      headers=HEADERS, files={"file": f.open("rb")})
    print(r.json()["mediaUrl"])
    f.rename(f.with_suffix(".uploaded"))

CI pipelines

Upload failure screenshots, coverage charts, or release banners straight from GitHub Actions and comment them on the PR — no artifact login required for reviewers.

Discord bots and webhooks

Bots can accept a file from chat, relay it through the API, and reply with a permanent link that survives the message scroll-back.

AI agents via MCP

dbimg also ships an MCP server, so agent frameworks with MCP support can upload media autonomously using the same infrastructure.

Response Field Reference

Every successful upload returns the same JSON shape, and knowing each field saves a documentation round-trip:

• id — internal identifier; useful for logs and support queries.
• shortId — the canonical slug; all URLs derive from it.
• customSlug — echoes your chosen slug when set, otherwise null.
• mediaUrl — the permanent direct CDN link for public uploads; protected uploads return their share page instead, by design.
• shareUrl — human-friendly landing page with embed snippets.
• deletionUrl — self-service delete endpoint requiring no login; store it if you upload anonymously.
• fileName / fileSize / mimeType — echo of what actually landed, after processing.
• hasPassword / expiresAt / maxViews — confirmation of the controls you applied.

Log at least mediaUrl and deletionUrl in any production integration; future-you will send thanks.

A Complete GitHub Actions Example

name: Upload failure screenshots\non:\n  workflow_run:\n    workflows: [Tests]\n    types: [failure]\njobs:\n  capture:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Upload artifact to dbimg\n        env:\n          DBIMG_KEY: ${{ secrets.DBIMG_KEY }}\n        run: |\n          curl -sS -X POST https://dbimg.app/api/upload \\\n            -H "Authorization: Bearer $DBIMG_KEY" \\\n            -F "file=@screenshots/failure.png" \\\n            -F "expiresIn=1w" | tee response.json\n          echo \"Link: $(jq -r .mediaUrl response.json)\"

The one-week expiry keeps failure evidence around for triage without polluting anyone’s storage forever — a pattern worth copying wherever screenshots are diagnostic rather than archival.

Designing Deletion Into Your Scripts

The deletionUrl is an underrated design surface. A nightly cleanup job can prune everything older than your retention window by replaying stored deletionUrls — no account credentials in CI secrets, no dashboard clicking. Support tooling can honour user requests by deleting exactly the file referenced. And self-destructing shares (maxViews plus expiry) mean many scripts never need deletion logic at all: build the expiry into the upload and let the platform do the janitorial work. Whichever route you take, treat deletion as part of the lifecycle you automate, not an afterthought for humans.

Retries, Idempotency, and Staying Sane

Networks fail; scripts should expect it. Wrap uploads in a retry with exponential backoff — attempt at once, then after two, four, eight seconds — and honour the Retry-After header on 503 responses rather than inventing your own delay. For critical uploads, make retries idempotent by checking the response: if a timeout left you unsure whether the file landed, upload again and simply use whichever shortId you keep — orphaned duplicates cost nothing and can be pruned via their deletionUrls. Log every response body, not just status codes; the error field tells you what actually happened, which turns support questions from archaeology into grep.

Slug Conventions That Scale

customSlug is more powerful than it looks when used as a naming system rather than a vanity. Teams converge on patterns like project-env-asset-purpose — acme-prod-banner-spring — which makes links self-documenting, greppable in logs, and collision-obvious. Reserve stable slugs for things that get re-pointed over time (release banners, status images) and let everything else take auto-generated slugs; the combination gives you memorable anchors where stability matters and zero naming overhead where it does not.

A Security Checklist for Integrations

• Keys live in secrets managers, never in repositories, logs, or client-side code.
• Scope by environment: separate keys for dev, staging, and production make blast radius calculable.
• Rotate quarterly and immediately on any suspicion — rotation takes minutes.
• Validate user input before forwarding files: size caps client-side save everyone bandwidth.
• Monitor your rate-limit headers; they are the API telling you its mood before it stops responding.

Frequently Asked Questions

What is the maximum file size over the API?

The same as the web: 75MB on free accounts, 250MB on Pro. The API is not a second-class citizen — identical limits, identical formats.

Can I rotate keys?

Yes — generate a new key from the dashboard, update your environments, revoke the old one. Rotation takes minutes and is good hygiene for anything running in CI.

Do anonymous uploads work from scripts?

Programmatic access requires a key by design — that is what makes fair rate limits possible. The free account plus key is the automation path; anonymity remains a web-upload feature.

Is there a client library?

The API is one endpoint with multipart semantics, so any HTTP library is a client. Wrap it once in your codebase and every team inherits the integration.

Organising Uploads From Scripts

Automation without organisation recreates the junk drawer at scale. Three habits keep programmatic uploads navigable: prefix every customSlug with a project or environment token so related uploads sort together; write the response JSON to a local log rather than parsing-and-forgetting, giving you a searchable history of what was uploaded when; and schedule a monthly replay of your deletionUrls for anything in a scratch namespace. Teams that adopt these three conventions report that finding last month’s build screenshot takes seconds instead of a Slack archaeology session — which is the entire return on investment.

Where to Go Next

The full parameter reference lives in the developer documentation. Grab a key from your dashboard, wire up one script, and reclaim the minutes you used to spend dragging files into browser tabs.