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.
curl -X POST https://api.usethrottle.dev/api/v1/media \
-H "x-api-key: $THROTTLE_SECRET_KEY" \
-F "alt=Blue ceramic mug" \
-F "[email protected]"
# 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/jpegis stored as a PNG, and an HTML file sent asimage/pngis 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).
<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.
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
httporhttpsand public. Private, loopback, link-local and cloud-metadata addresses (IPv4 and IPv6) are refused with400 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.limitis 1 to 200 (default 50),qmatches alt text ignoring case, andmimefilters on an exact type such asimage/png. Page withnextCursor. -
GET /api/v1/media/{id}: one image. A deleted image is still returned, withdeletedAtset, 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.
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. 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 nofilepart.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.