canonical: https://jentic.com/apis/api.imgix.com/imgix

# imgix Management API

The imgix Management API controls the configuration and content of imgix image sources, the assets they hold, the cache that fronts them, and the analytics they generate. Agents can list and create sources backed by S3, GCS, Azure, or Web Folder origins, manage the assets in each source, queue assets from origin, refresh existing assets, purge URLs from the imgix CDN cache, and pull usage and bandwidth reports. Image transformation itself happens at the imgix render domain - this API is for managing the underlying configuration.

## For AI agents

Manage imgix image sources, assets, and cache purges, and pull bandwidth and usage reports - without rendering images directly.

## Scope

Does not handle on-the-fly image rendering, video transcoding, or generic file storage - use for managing imgix sources, assets, and cache purges only.

## Capabilities

- Create and update image sources backed by S3, GCS, Azure Blob, or Web Folder origins
- List and inspect assets within a source, including file size, dimensions, and origin path
- Upload an asset directly to an imgix source or queue it for ingestion from origin
- Refresh an asset to force re-fetch from origin after a source-side change
- Purge a single asset URL from the imgix CDN cache so the next request re-renders
- Update asset metadata such as alt text or custom fields used by image transformation rules
- Retrieve usage and bandwidth reports at the account level

## Use cases

### Content Source Provisioning

Provision a new imgix source automatically when a new tenant or microsite is created. The POST /sources endpoint creates a source bound to an existing origin (S3, GCS, Azure, or Web Folder), returning the source ID needed to construct render URLs. Pair with PATCH `/sources/{source_id}` to update origin credentials or enable secure URLs without manual dashboard work.

Example prompt: Call POST /sources with type 's3' and the bucket and prefix for the new tenant, then return the created source_id and base render URL.

### CDN Cache Invalidation

Invalidate stale image URLs from the imgix cache when the origin asset is replaced. POST `/api/v1/purge` accepts a single URL and queues it for purge across the imgix global cache, so the next render fetches the updated origin file. This is essential when CMS editors update images in place rather than versioning the filename.

Example prompt: Call POST `/api/v1/purge` with the URL https://example.imgix.net/hero.jpg to evict the stale render.

### Asset Catalogue Audit

Audit the assets in a source for cleanup or governance - find oversized files, missing alt text, or unused origin paths. GET `/sources/{source_id}/assets` paginates through assets with size and metadata; PATCH `/sources/{source_id}/assets/{origin_path}` updates fields where a fix is required. This replaces manual exports of S3 inventories.

Example prompt: List assets in source 'tenant-prod', filter to those with file_size over 5 MB, and return the origin_path list for review.

### AI Agent Image Operations

An AI agent managing a marketing site can use imgix via Jentic to provision sources, upload new assets, and purge URLs as content changes - all without holding the bearer token in agent context. Jentic surfaces the source, asset, and purge endpoints as discoverable tools chosen by intent.

Example prompt: Search for 'purge an imgix asset from cache', load the POST `/api/v1/purge` schema, and execute it with the URL provided by the agent's input.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/sources` | List all image sources |
| POST | `/sources` | Create a new image source |
| PATCH | `/sources/{source_id}` | Update an image source's configuration |
| GET | `/sources/{source_id}/assets` | List assets in a source |
| POST | `/sources/{source_id}/upload/{origin_path}` | Upload an asset to a source |
| POST | `/api/v1/purge` | Purge an asset URL from the imgix cache |
| GET | `/api/v1/reports` | List usage and bandwidth reports |

## Key resources

- **Sources** — Image sources backed by S3, GCS, Azure, or Web Folder origins
- **Assets** — Individual image files within a source, with size and metadata
- **Purge** — Cache purge requests against the imgix CDN
- **Reports** — Account-level usage and bandwidth analytics

## Why Jentic

- **Setup:** Wiring the imgix Management API by hand means setting up its bearer token auth and coding your own calls to the sources, assets, and purge endpoints. Through Jentic you install once, import the imgix Management API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** imgix puts the source id in the URL path (`/sources/{source_id}`, `/sources/{source_id}/assets`), so a rule can pin your agent to one source. You choose the operations it may call, so updating a source or issuing a cache purge are not included unless you add them.
- **Credential handling:** Your imgix token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list assets for a source' or 'purge a cached asset', and Jentic returns the matching imgix operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloudinary Admin API** — Cloudinary bundles asset storage, transformation, and a Media Library; imgix focuses on URL-based transformations over your own origin
- **Filestack API** — Filestack focuses on file ingestion, transformation, and delivery as a single API; imgix focuses on transformation over existing origins
- **Kraken.io API** — Kraken.io specialises in image optimisation; imgix handles dynamic rendering and CDN delivery

## FAQ

### What authentication does the imgix Management API use?

imgix Management uses HTTP Bearer authentication - a personal access token is passed as Authorization: Bearer <token>. When called through Jentic, the token is stored encrypted in your Jentic One instance and attached at execution time, so it never appears in agent context.

### Can I render or transform images with the Management API?

No. Image rendering and transformation happen at the imgix render domain (e.g. yoursource.imgix.net) where transformation parameters are passed in the URL. The Management API only configures sources, manages assets, and handles cache purges - the rendering pipeline is a separate, URL-driven service.

### What are the rate limits for the imgix Management API?

imgix applies modest rate limits to the Management API; sustained high-volume usage should be discussed with imgix support. Cache purge requests in particular are billed per purge on most plans, so coordinate purges with content updates rather than running speculative purge sweeps.

### How do I purge a stale image URL through Jentic?

Run pip install jentic, then search for 'purge an image from the imgix cache'. Jentic returns the POST `/api/v1/purge` operation. Load its schema, pass the full render URL you want evicted, and execute. The next request to that URL will re-fetch from origin.

### Is the imgix Management API free to use?

imgix charges based on processed images, bandwidth, and cache purges; the Management API itself does not have a separate price, but operations it triggers (such as ingesting new assets or purging URLs) draw from your account's billable usage. Check imgix pricing for current rates.

### Can I queue an asset that lives at the origin without uploading it?

Yes. POST `/sources/{source_id}/assets/add/{origin_path}` queues an asset for ingestion from the configured origin so imgix can prepare and serve it. This is useful when files are deposited directly into S3 or another origin and you want imgix to register and warm them ahead of first request.

### Can I limit what my agent is allowed to do with the imgix Management API?

Yes. Because Jentic One is self-hosted, your own rules decide which imgix operations and credentials the agent may use. imgix puts the source id in the URL path (for example `/sources/{source_id}` and `/sources/{source_id}/assets`), so a rule can pin the agent to a single source. You also choose the operations it may call, so actions like updating a source with PATCH `/sources/{source_id}` or issuing a cache purge with POST `/api/v1/purge` stay off limits unless you add them.