API Reference
Use the API reference when you need exact Resource API endpoint paths, request fields, response schemas, enum values, and generated request examples.
Overview
The interactive REST API Reference is generated from Imgwire's OpenAPI schema:
https://api.imgwire.dev/api/v1/openapi-server.json
The reference is the source of truth for endpoint-level details. These Resource API guide pages explain how the endpoint groups fit into real integration workflows.
Endpoint groups
| Group | Endpoints |
|---|---|
| CORS Origins | GET /api/v1/cors_origins/, POST /api/v1/cors_origins/, GET/PATCH/DELETE /api/v1/cors_origins/{cors_origin_id} |
| Custom Domain | GET /api/v1/custom_domain/, POST /api/v1/custom_domain/, DELETE /api/v1/custom_domain/, POST /api/v1/custom_domain/test_connection |
| Images | GET /api/v1/images/, POST /api/v1/images/standard_upload, POST /api/v1/images/upload_via_url, POST /api/v1/images/token, GET/DELETE /api/v1/images/{image_id} |
| Image downloads | POST /api/v1/images/downloads, GET /api/v1/images/downloads/{image_download_job_id} |
| Bulk image delete | POST /api/v1/images/bulk_delete |
| Metrics | GET /api/v1/metrics/datasets, GET /api/v1/metrics/stats |
Authentication conventions
Most Resource API requests use a Server API Key:
Authorization: Bearer <SERVER_API_KEY>
Server API Keys are scoped to an Imgwire Environment. If you authenticate with a user session or an OAuth-linked agent instead of an environment-scoped API key, include:
X-Environment-Id: <ENVIRONMENT_ID>
Client Keys are supported only for specific image operations such as standard upload creation and image lookup. Do not use Client Keys for management operations such as metrics, CORS origin management, custom domain management, URL uploads, upload token creation, or deletes.
Request and response conventions
The Resource API uses JSON request and response bodies for management operations. Upload bytes are not sent to the Resource API directly during a standard upload. Instead, POST /api/v1/images/standard_upload returns an upload_url, and your client uploads the image bytes directly to that presigned URL.
List endpoints use page and limit query parameters:
| Query parameter | Default | Notes |
|---|---|---|
page | 1 | Must be at least 1 |
limit | 20 | Must be between 1 and 100 |
Pagination metadata is returned in response headers:
X-Total-Count: 42
X-Page: 1
X-Limit: 20
X-Prev-Page: null
X-Next-Page: 2
Validation errors return a structured detail array with a location, message, and error type.
Example request
curl "https://api.imgwire.dev/api/v1/metrics/stats?interval=DAILY&tz=UTC" \
-H "Authorization: Bearer $IMGWIRE_API_KEY"
Related pages
Last updated at: May 9, 2026