Regions, clouds, and API endpoints

TL;DR

• Your stack's region is locked at creation and determines every API base URL your code targets.
• Use the SDK's built-in region constants instead of hardcoding base URLs -- the SDK constructs the correct endpoints automatically.
• When credentials are correct but requests return 401 or empty results, verify the region first -- error messages never mention a region mismatch.

Contentstack operates across multiple cloud providers and geographic regions. When you create a stack, you choose a region. That choice determines which data center hosts your content and which base URLs every API call targets. Getting the region wrong is one of the most common causes of silent failures - requests return empty results or authentication errors with no indication that the URL itself is the problem.

This lesson maps out Contentstack's infrastructure so you can configure projects correctly, debug region-related issues quickly, and make informed decisions about where your content lives.

Why regions matter

Three concerns drive the multi-region architecture:

1. Data residency - Regulated industries and regional privacy laws (GDPR, data sovereignty requirements) may mandate that content data stays within a specific geography. Choosing the correct region ensures compliance at the infrastructure level.
2. Latency - API responses are faster when the data center is geographically closer to your server or edge function. While Contentstack's CDN layer mitigates this for cached delivery requests, management API calls and cache misses benefit from regional proximity.
3. Cloud provider preference - Some organizations have existing commitments to AWS, Azure, or GCP. Contentstack supports all three, so you can align your CMS infrastructure with your broader cloud strategy.

Available regions

Contentstack currently offers seven regions across three cloud providers:

Your region is locked at stack creation. You cannot migrate a stack between regions after creation. If you need to move content to a different region, you must create a new stack in the target region and migrate content using the CLI or Management API.

How to find your stack's region

Open the Contentstack dashboard and navigate to Settings > Stack. The region is displayed in the stack information panel. You can also identify it from the URL in your browser - the dashboard URL includes a region indicator (for example, eu-app.contentstack.com for the AWS Europe region, or azure-na-app.contentstack.com for Azure North America).

API endpoints by region

Every Contentstack API surface has a different base URL per region. The tables below cover the endpoints you will use most frequently as a developer.

Core APIs

Assets and images

Platform services

Tip:

These endpoints are sourced from the official Contentstack regions data. For the most up-to-date list, see the Contentstack API endpoints documentation. The @timbenniks/contentstack-endpoints package auto-syncs with this same data source weekly.

The URL naming pattern

Notice the naming convention across all endpoints. AWS North America uses the base domain without a prefix (cdn.contentstack.io, api.contentstack.io). Every other region prepends a region identifier:

• AWS EU: eu- prefix (e.g., eu-cdn.contentstack.com)
• AWS AU: au- prefix (e.g., au-cdn.contentstack.com)
• Azure NA: azure-na- prefix (e.g., azure-na-cdn.contentstack.com)
• Azure EU: azure-eu- prefix (e.g., azure-eu-cdn.contentstack.com)
• GCP NA: gcp-na- prefix (e.g., gcp-na-cdn.contentstack.com)
• GCP EU: gcp-eu- prefix (e.g., gcp-eu-cdn.contentstack.com)

Also note that AWS NA uses the .io TLD (contentstack.io) while all other regions use .com (contentstack.com). This is a common source of copy-paste errors.

SDK region configuration

When you use @contentstack/delivery-sdk, the SDK handles URL construction for you. You set the region during initialization and the SDK routes all requests to the correct endpoints.

import Contentstack from "@contentstack/delivery-sdk";

const stack = Contentstack.stack({
  apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY,
  deliveryToken: process.env.NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN,
  environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT,
  region: Contentstack.Region.EU,
});

The SDK exposes region constants that map to the correct base URLs:

When you set the region, the SDK constructs the correct CDN, API, and asset URLs automatically. You never need to hardcode base URLs in your application.

Resolving endpoints beyond the Delivery SDK

The Delivery SDK handles region routing for content fetching, but Live Preview and Visual Builder require additional region-specific URLs that the SDK does not expose directly -- specifically the REST Preview host (for the live_preview config) and the Application host (for clientUrlParams.host in the Live Preview SDK). These are covered in Course 4: Live Preview and Visual Builder.

The community package @timbenniks/contentstack-endpoints provides a lightweight helper that maps a region string to every Contentstack endpoint URL. It has zero dependencies and stays in sync with the official regions data.

import { getContentstackEndpoints } from "@timbenniks/contentstack-endpoints";

const endpoints = getContentstackEndpoints(process.env.CONTENTSTACK_REGION || "na");

endpoints.contentDelivery;  // e.g. https://eu-cdn.contentstack.com
endpoints.preview;          // e.g. https://eu-rest-preview.contentstack.com
endpoints.application;      // e.g. https://eu-app.contentstack.com
endpoints.graphqlPreview;   // e.g. https://eu-graphql-preview.contentstack.com

Pass true as the second argument to strip the https:// prefix, which is what the Live Preview SDK expects for host values:

const endpoints = getContentstackEndpoints("eu", true);
endpoints.preview;      // eu-rest-preview.contentstack.com
endpoints.application;  // eu-app.contentstack.com

This is a convenience wrapper -- you can always look up the correct host from the tables above and set it manually. The package eliminates the risk of hardcoding the wrong host for your region.

Debugging region mismatches

Common pitfall: A wrong region produces 401 or empty-result errors with no indication that the URL itself is the problem -- making it one of the hardest misconfigurations to diagnose.

A wrong region is one of the hardest issues to debug because the error messages do not tell you the region is wrong. Here is what you typically see:

• 401 Unauthorized - The API key and token are valid, but for a different region's endpoint. The target region does not recognize them.
• Empty results - The request succeeds (200 status) but returns zero entries because the stack does not exist in the region you are querying.
• 412 Precondition Failed - Some region/credential combinations produce this instead of a 401.

If you encounter any of these and your credentials are correct, verify the region first. Check Settings > Stack in the dashboard and compare the region against your SDK configuration or API base URL.

A quick diagnostic: make the same request with curl using the base URL for the region shown in your dashboard. If that works but your application does not, your application is targeting the wrong endpoint.

# Test against AWS NA
curl -s -o /dev/null -w "%{http_code}" \
  -H "api_key: YOUR_API_KEY" \
  -H "access_token: YOUR_DELIVERY_TOKEN" \
  "https://cdn.contentstack.io/v3/content_types/YOUR_CONTENT_TYPE/entries?environment=YOUR_ENV"

# Test against AWS EU
curl -s -o /dev/null -w "%{http_code}" \
  -H "api_key: YOUR_API_KEY" \
  -H "access_token: YOUR_DELIVERY_TOKEN" \
  "https://eu-cdn.contentstack.com/v3/content_types/YOUR_CONTENT_TYPE/entries?environment=YOUR_ENV"

One of these returns 200, the other returns 401 or 412. The one that returns 200 is your actual region.