Media

Media library

Each store (an application in one environment) has one library of images. Upload a file or give Throttle a URL, and you get back a public URL for the original plus WebP copies at fixed widths, ready for srcset. A sandbox environment has its own library, separate from production.

Scopes

media:read lists and reads images. media:write uploads, renames and deletes them, and includes media:read. Extensions may request both. A publishable key (pk_) cannot hold either. A dashboard session needs the Settings permission on the application to write. See scopes.

Upload an image

POST /api/v1/media takes multipart/form-data with a file part and an optional alt field (up to 500 characters). It answers 201 with the image.

Upload
curl -X POST https://api.usethrottle.dev/api/v1/media \
  -H "x-api-key: $THROTTLE_SECRET_KEY" \
  -F "alt=Blue ceramic mug" \
  -F "file=@mug.png"

# 201
{
  "data": {
    "id": "5b0c7a52-9e0b-4a53-8f67-0d6f1d6a7c11",
    "url": "https://api.usethrottle.dev/api/v1/assets/workspaces/<ws>/applications/<app>/environments/<env>/media/01J9ZQ4M6X8Y3N2T5V7W9B1C3D.png",
    "mime": "image/png",
    "bytes": 482113,
    "width": 1100,
    "height": 700,
    "alt": "Blue ceramic mug",
    "variants": [
      { "width": 320, "url": ".../media/01J9ZQ4M6X8Y3N2T5V7W9B1C3D-320.webp" },
      { "width": 640, "url": ".../media/01J9ZQ4M6X8Y3N2T5V7W9B1C3D-640.webp" },
      { "width": 1024, "url": ".../media/01J9ZQ4M6X8Y3N2T5V7W9B1C3D-1024.webp" }
    ],
    "createdAt": "2026-11-15T09:30:00.000Z",
    "deletedAt": null
  },
  "meta": { "requestId": "req_..." }
}
  • Types: PNG, JPEG, WebP, GIF and AVIF. SVG is refused. Throttle reads the type from the file's own bytes and ignores the declared content type: a PNG sent as image/jpeg is stored as a PNG, and an HTML file sent as image/png is refused.
  • Size: at most 10 MB and 40 megapixels (a 9000 by 9000 image is too big).
  • Privacy: a JPEG original is stored without its EXIF data (GPS position, camera, editing software). Its pixels, quality and orientation are unchanged. Other formats are stored exactly as uploaded, and variants are WebP files with no metadata.
  • Animated GIFs keep their animation in the original. Variants use the first frame.
  • Variants: WebP copies at 320, 640, 1024, 1600 and 2400 pixels wide, listed in variants. A variant is never larger than the original, so a 1100 pixel wide image has variants at 320, 640 and 1024.
  • Store limits: 60 uploads a minute, 10,000 images and 5 GB of originals. Deleted images stop counting toward the 10,000 right away, but their size counts toward the 5 GB until their files are removed (see below).
Build srcset from variants
<img
  src="{asset.url}"
  srcset="{asset.variants.map((v) => v.url + ' ' + v.width + 'w').join(', ')}"
  sizes="(min-width: 1024px) 50vw, 100vw"
  width="{asset.width}" height="{asset.height}"
  alt="{asset.alt}" />

Add an image from a URL

POST /api/v1/media/from-url with { url, alt? } makes Throttle download the image and add it, with the same rules and the same 201 answer as an upload.

From a URL
curl -X POST https://api.usethrottle.dev/api/v1/media/from-url \
  -H "x-api-key: $THROTTLE_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "url": "https://cdn.example.com/hero.jpg", "alt": "Hero" }'
  • The URL must be http or https and public. Private, loopback, link-local and cloud-metadata addresses (IPv4 and IPv6) are refused with 400 url_not_allowed, whether they are in the URL, behind a host name, or reached by a redirect.
  • At most 3 redirects, each checked again (422 too_many_redirects).
  • The download stops at 10 MB (413 file_too_large).
  • The bytes must be one of the image types above (415 unsupported_media_type).
  • A download that fails or times out is 502 fetch_failed.

List, read, rename and delete

  • GET /api/v1/media: images, newest first, without deleted ones. limit is 1 to 200 (default 50), q matches alt text ignoring case, and mime filters on an exact type such as image/png. Page with nextCursor.
  • GET /api/v1/media/{id}: one image. A deleted image is still returned, with deletedAt set, so a page that uses it can be flagged.
  • PATCH /api/v1/media/{id} with { alt }: change the alt text.
  • DELETE /api/v1/media/{id}: soft delete. The image leaves the list and stops counting toward the 10,000 images. Its files stay in storage and keep their URLs for 30 days, so a page that still uses the image keeps working. After that Throttle removes the files and the URLs stop working. Deleting twice is safe.
List
curl "https://api.usethrottle.dev/api/v1/media?q=mug&limit=24" \
  -H "x-api-key: $THROTTLE_SECRET_KEY"

# 200, newest first
{
  "data": [ { "id": "5b0c7a52-...", "alt": "Blue ceramic mug", "...": "..." } ],
  "nextCursor": "MjAyNi0xMS0xNVQwOTozMDowMC4wMDBafDViMGM3YTUy...",
  "meta": { "requestId": "req_..." }
}

# Next page: pass nextCursor back as ?cursor=. The last page has "nextCursor": null.
One store only
An image belongs to one application and environment. Asking for it with a key from another environment answers 404 not_found.

The url and every variant url are public and cached for a year, so a changed picture needs a new upload. They sit under /api/v1/assets/workspaces/{workspace}/applications/{application}/environments/{environment}/media/.

Errors

  • 400 no_file: the multipart body had no file part.
  • 413 file_too_large: over 10 MB.
  • 415 unsupported_media_type: not a PNG, JPEG, WebP, GIF or AVIF image.
  • 422 image_too_large: over 40 megapixels. 422 invalid_image: the file is damaged.
  • 429 rate_limited: more than 60 uploads in a minute for this store.
  • 409 media_quota_exceeded: the store holds 10,000 images or 5 GB of originals (deleted images count toward the 5 GB until their files are removed).
  • 404 not_found: no such image in this environment.