API Proxy Overview

CMS Assets supports two complementary proxy layers on the same project:

• Asset proxy for media delivery and edge caching
• API proxy for read-only CMS API requests through your-project.cmsassets.com/~api

The recommended setup uses both: route read-only CMS API requests through the API proxy, keep tokens server-side, cache responses at the edge, and return proxy-ready asset URLs automatically. Asset-only usage is the lighter alternative for when you only need media delivery.

Recommended setup

The strongest CMS Assets setup is:

1. proxy read-only CMS API requests through https://your-project.cmsassets.com/~api/...
2. inject credentials server-side
3. cache API responses at the edge
4. rewrite asset URLs in JSON responses to https://your-project.cmsassets.com/...

That gives your app a single proxy layer for both CMS data and asset delivery.

Asset proxy vs API proxy

API proxy

Use API proxy when you want to:

• route read-only CMS API requests through https://your-project.cmsassets.com/~api/...
• keep CMS credentials server-side
• cache API responses at the edge
• return proxy-ready asset URLs in JSON responses

API proxy is GET only. It is designed for fetching CMS content safely and efficiently, not for writes, uploads, deletes, or admin mutations.

Asset proxy only

Use asset proxy on its own when you want to:

• serve CMS media through https://your-project.cmsassets.com/...
• cache images, files, and videos at the edge
• reduce origin bandwidth and control overage costs
• keep implementation as small as possible

This is the lighter path, but it does not replace the API proxy when you also want proxied CMS responses and server-side credential handling.

One edge domain for both

The same project handles both flows:

Asset request: https://your-project.cmsassets.com/path/to/image.jpg
API request:   https://your-project.cmsassets.com/~api/spaces/abc/entries

That means you can:

1. create one project
2. use the API proxy by default
3. fall back to asset-only mode when you want less surface area

Common rollout paths

API + asset proxy

Best when you want CMS Assets to handle the full delivery layer:

• create a project
• route read-only CMS API requests through /~api
• configure apiOrigin, auth mode, token header, and token
• keep parsed responses enabled so asset URLs are already rewritten

This is the recommended path.

Asset proxy only

Best when you want the smallest implementation step:

• create a project
• route asset URLs through your edge domain
• keep your existing CMS API calls unchanged

This path works well with the CLI, response transformer, SDK, or a small URL rewrite step in your CMS client.

Parsed vs raw API responses

By default, CMS Assets can rewrite asset URLs inside JSON API responses so your app receives proxy-ready URLs.

• default behavior: parsed response with rewritten asset URLs
• ?parsed=false: raw proxied response without URL rewriting
• transformApiUrls=false: disable JSON URL rewriting at the project level

This is useful when one consumer wants tenant URLs while another needs the raw upstream payload.

When asset-only is enough

You can stay with asset-only mode when:

• your CMS API credentials are already handled elsewhere
• you only need proxied media delivery
• you want the smallest rollout possible

You should still use the API proxy when:

• your frontend should not see CMS tokens
• you want edge caching for read-heavy CMS endpoints
• you want asset URLs rewritten before the response reaches your app
• you want one edge domain for both asset and API traffic

Next steps

• Getting Started — Choose the right setup path
• Configuring API Proxy — Set up apiOrigin, token injection, and caching
• How It Works — See request flow and cache behavior
• Admin API — Reference for tenant and API proxy endpoints