Configuring API Proxy

CMS Assets can proxy read-only CMS API requests through:

https://your-project.cmsassets.com/~api/...

This guide walks through the project-level configuration needed to enable the API proxy, where read-only CMS API requests are proxied and parsed responses can already contain proxy-ready asset URLs.

What API proxy gives you

When API proxy is enabled for a project, CMS Assets can:

• forward GET requests to your upstream CMS API
• inject credentials server-side
• cache API responses at the edge
• optionally rewrite asset URLs inside JSON responses to your edge domain

This is the primary CMS Assets flow. Asset proxy can still be used independently, but API proxy with asset URL rewriting is the setup that gives you the most value.

1. Set the API origin

Set apiOrigin to the upstream base URL of the CMS API you want to proxy.

Examples:

https://api.cloudinary.com/v1_1/my-cloud
https://cdn.contentful.com/spaces/abc123
https://api.storyblok.com/v2/cdn

Every proxied request strips the /~api prefix and appends the remaining path to this origin.

2. Choose the auth mode

Use apiAuthMode to control how CMS Assets injects credentials into upstream requests.

• bearer — sends Bearer <token>
• basic — sends Basic <token>
• token — sends Token <token>
• none — sends no auth header

For example, Cloudinary Admin API requests typically use basic.

3. Set the token header

Use apiTokenHeader when your upstream CMS expects a specific header name.

Default:

Authorization

In most cases you can leave this as-is.

4. Configure API cache TTL

Use apiCacheTTL to control how long API responses stay cached at the edge.

• default: 60 seconds
• supported range: 10 to 3600 seconds

Choose a lower TTL for frequently changing content and a higher TTL for read-heavy endpoints with stable responses.

5. Configure preview bypass

Use previewBypassParam to bypass API cache for preview flows.

Default:

preview

If the proxied request includes that param, CMS Assets skips the API cache and fetches the upstream CMS API directly.

Example:

https://your-project.cmsassets.com/~api/stories/home?preview=1

Using bypass from your app code

If you use createCmsAssetsFetch from @synchronized-studio/cmsassets-core, you can wrap the fetch function to append the bypass param automatically when preview or fresh-fetch mode is active:

import { createCmsAssetsFetch } from '@synchronized-studio/cmsassets-core'

const baseFetch = createCmsAssetsFetch({ tenant: 'my-site', provider: 'prismic' })

// Wrap with a bypass signal — evaluated per request
function withCacheBypass(baseFetch, shouldBypass) {
  return function (input, init) {
    if (!shouldBypass()) return baseFetch(input, init)
    const url = typeof input === 'string' ? input : input.url
    const parsed = new URL(url)
    if (!parsed.searchParams.has('preview')) {
      parsed.searchParams.set('preview', '1')
    }
    return baseFetch(parsed.toString(), init)
  }
}

const cmsFetch = withCacheBypass(baseFetch, () => isPreviewActive)

See the Prismic integration guide for a complete Nuxt example.

Preview bypass only affects API proxy routes (/~api). Asset proxy requests are not affected.

6. Decide whether to rewrite asset URLs

Use transformApiUrls to control whether JSON API responses should have CMS asset URLs rewritten to your project's edge domain.

• true — parsed response with rewritten asset URLs
• false — keep original upstream asset URLs

This setting is useful when you want API responses to already contain proxy-ready asset URLs before they reach your app.

7. Save the token

Store the CMS API token using the write-only token endpoint or the admin UI.

Important details:

• tokens are stored encrypted
• tokens are never returned to the client
• tokens are injected only when the worker needs to call the upstream API

For Cloudinary basic auth, the token value should be:

btoa("api_key:api_secret")

8. Test the proxied URL

After configuration, send a GET request through your project:

https://your-project.cmsassets.com/~api/...

You should verify that the request:

• reaches the correct upstream path
• authenticates successfully
• returns the expected content

9. Check cache and parsing headers

Inspect the response headers:

• X-Cache: HIT, MISS, or BYPASS
• X-Parsed: true when JSON URL rewriting is enabled

These headers tell you whether the response came from API cache and whether the body was parsed for asset URL rewriting.

10. Use raw mode when needed

If you want the proxied upstream response without JSON asset URL rewriting, add:

?parsed=false

Example:

https://your-project.cmsassets.com/~api/spaces/abc/entries?parsed=false

This is helpful when one consumer needs raw CMS output while another wants proxy-ready URLs.

Summary

The recommended activation flow looks like this:

1. create a project
2. add apiOrigin, auth mode, and token
3. keep parsed responses enabled
4. decide whether transformApiUrls should stay enabled
5. test /~api and verify X-Cache / X-Parsed

That gives you one edge domain for both proxied CMS responses and asset delivery. If you later decide you only want media delivery, you can still use the asset proxy on its own.

Next steps

• API Proxy Overview — Understand when to use each proxy mode
• How It Works — Review request flow and cache behavior
• Admin API — Full reference for api-config, api-token, and cache refresh endpoints