Images

Use the Images Resource API to create uploads, ingest remote image URLs, retrieve image records, delete images, issue upload tokens, and prepare bulk downloads.

Overview

An Imgwire image record tracks the uploaded file, processing status, delivery URL, metadata, dimensions, MIME type, and lifecycle fields for one image in an Environment.

Image records include fields such as:

Field	Meaning
id	Image UUID
status	PENDING, PROCESSING, READY, or QUARANTINE
cdn_url	Base CDN delivery URL for the image
mime_type	Original image MIME type
width, height, size_bytes	Processed image metadata
custom_metadata	String, number, integer, or boolean metadata you attach at upload time
exif_data	Extracted metadata where available
processed_metadata_at	When image metadata processing completed

Endpoints

Method	Path	Purpose	Auth
GET	/api/v1/images/	List images	Server Key
POST	/api/v1/images/standard_upload	Create an upload and return a presigned upload_url	Server Key or Client Key
POST	/api/v1/images/upload_via_url	Ingest an image from a remote URL	Server Key
POST	/api/v1/images/token	Create an upload token for signed frontend uploads	Server Key
GET	/api/v1/images/{image_id}	Retrieve an image by ID	Server Key or Client Key
DELETE	/api/v1/images/{image_id}	Delete an image	Server Key
POST	/api/v1/images/bulk_delete	Delete multiple images	Server Key
POST	/api/v1/images/downloads	Create a bulk download job	Server Key
GET	/api/v1/images/downloads/{image_download_job_id}	Retrieve a bulk download job	Server Key

Standard upload

Use standard uploads when your application already has local file bytes. First create the Imgwire image record and presigned upload URL:

curl https://api.imgwire.dev/api/v1/images/standard_upload \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "hero.png",
    "mime_type": "image/png",
    "content_length": 348221,
    "purpose": "marketing_hero",
    "custom_metadata": {
      "source": "cms",
      "published": true
    }
  }'

The response contains an image record and upload_url:

{
  "image": {
    "id": "8b93b7a8-8891-4d46-95ed-1137324c4549",
    "status": "PENDING",
    "cdn_url": "https://cdn.imgwire.dev/6b024480-a5ac-426d-b539-2e4fccc4c6ac/26f80c13-48bd-4bb9-866e-5e9392b11a6a/8b93b7a8-8891-4d46-95ed-1137324c4549",
    "mime_type": "image/png",
    "can_upload": true,
    "is_directly_deliverable": true
  },
  "upload_url": "https://..."
}

Then upload the file bytes directly to the returned upload_url with the same content type:

curl "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: image/png" \
  --upload-file ./hero.png

Do not send image bytes to the Resource API request body.

Upload from a remote URL

Use URL uploads when an image already exists at a temporary or public asset URL, such as an image-generation platform result:

curl https://api.imgwire.dev/api/v1/images/upload_via_url \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/generated/astronaut.png",
    "purpose": "ai_generated_docs_image",
    "custom_metadata": {
      "model": "gpt-images",
      "page": "setup"
    }
  }'

file_name and mime_type are optional for URL uploads. Imgwire can infer them from the source URL and response metadata where possible.

Signed upload tokens

Create an upload token when a Client Key requires signed uploads:

curl https://api.imgwire.dev/api/v1/images/token \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

Return the token field from your backend to your frontend, then include it as the upload_token query parameter when creating a standard upload with the Client Key.

List and retrieve images

curl "https://api.imgwire.dev/api/v1/images/?page=1&limit=20" \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

curl https://api.imgwire.dev/api/v1/images/8b93b7a8-8891-4d46-95ed-1137324c4549 \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

List responses are arrays and include pagination headers. Retrieve responses return one Image record.

Delete and bulk delete

Delete one image:

curl https://api.imgwire.dev/api/v1/images/8b93b7a8-8891-4d46-95ed-1137324c4549 \
  -X DELETE \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

Bulk delete images:

curl https://api.imgwire.dev/api/v1/images/bulk_delete \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_ids": [
      "8b93b7a8-8891-4d46-95ed-1137324c4549",
      "bb682a30-b363-4d8a-b3d4-6ecb251d0917"
    ]
  }'

Bulk delete requires at least one image ID.

Bulk downloads

Create a bulk image download job:

curl https://api.imgwire.dev/api/v1/images/downloads \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_ids": [
      "8b93b7a8-8891-4d46-95ed-1137324c4549"
    ]
  }'

Retrieve the job until it is ready:

curl https://api.imgwire.dev/api/v1/images/downloads/37a59b6f-1f71-46d2-8dd5-215bf9ac0505 \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

Download job statuses are PENDING, PROCESSING, READY, and FAILED. When a job is ready, the response includes download_url.

Supported MIME types

The Resource API accepts these image MIME types:

image/jpeg
image/jxl
image/png
image/webp
image/avif
image/gif
image/vnd.microsoft.icon
image/heic
image/bmp
image/tiff

Best practices

• Use Server API Keys for backend image management and Client Keys only for frontend-safe upload flows.
• Use idempotency_key when retrying upload creation to avoid duplicate image records.
• Store image.id in your application data when you need future retrieval, deletion, bulk downloads, or transformations.
• Use purpose and custom_metadata to make image records easier to organize.
• Poll or retrieve image records when your app needs dimensions, extracted metadata, or final processing status.

Common mistakes

• Sending file bytes to standard_upload instead of uploading bytes to the returned upload_url.
• Exposing a Server API Key in frontend code.
• Assuming cdn_url is private authorization. CDN image delivery URLs are for delivery, not secret access control.
• Forgetting to configure CORS Origins when using Client Keys from a production browser app.
• Treating PENDING as a completed processing state.

Related pages

• Backend Quickstart
• Frontend Quickstart
• CORS Origins
• Custom Domain
• Metrics
• API Reference

Last updated at: May 9, 2026