Session Regions

Set sessionOptions.region when you need a session to start in a specific engine region. Anam supports two engine regions:

Value	Engine location
`eu`	Europe
`us`	United States

Enterprise plans only. Session region selection is available on Enterprise plans; requests from other plans return 403.

If you omit region, Anam selects a region from the request location and its current routing policy. An explicit region takes precedence over that automatic selection, even when automatic geographic routing is disabled.

Request a region

For browser clients, set the region when your server creates the session token. The region is bound to the token and cannot be replaced when the browser starts the session.

const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    personaConfig: {
      personaId: "00000000-0000-0000-0000-000000000000",
    },
    sessionOptions: {
      region: "eu",
      regionPolicy: "strict",
    },
  }),
});

if (!response.ok) {
  throw new Error(`Session token request failed: ${response.status}`);
}

const { sessionToken } = await response.json();

import os
import requests

response = requests.post(
    "https://api.anam.ai/v1/auth/session-token",
    headers={
        "Authorization": f"Bearer {os.environ['ANAM_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "personaConfig": {
            "personaId": "00000000-0000-0000-0000-000000000000",
        },
        "sessionOptions": {
            "region": "eu",
            "regionPolicy": "strict",
        },
    },
)
response.raise_for_status()
session_token = response.json()["sessionToken"]

curl -X POST https://api.anam.ai/v1/auth/session-token \
  -H "Authorization: Bearer $ANAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personaConfig": {
      "personaId": "00000000-0000-0000-0000-000000000000"
    },
    "sessionOptions": {
      "region": "eu",
      "regionPolicy": "strict"
    }
  }'

Server-side SDKs that start sessions directly use the same fields. In the Python SDK, pass SessionOptions(region="eu", region_policy="strict").

Choose a region policy

regionPolicy controls what happens when the requested region cannot accept the session.

Policy	Behavior
`preferred`	Uses the requested region first but may fail over to the other region when capacity is unavailable. This is the default.
`strict`	Never serves the session from another region. Requires an explicit `region`.

Use strict for data-residency requirements. Anam returns 400 if you set regionPolicy to strict without a region. Requests that set region or regionPolicy return 403 with the error code session_region_not_available when session region selection is not enabled for the organization. If the strict region is unavailable or out of capacity, session start returns 503. Wait briefly before trying the same region again. Anam does not retry a strict session in another region.

Read the served region

A successful engine-session response can include the region that actually served it:

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "region": "eu"
}

Under preferred, this value can differ from the requested region after a capacity failover. The field is absent when the serving session service does not report its region, so do not infer it from the requested region. In the JavaScript SDK, call client.getActiveSessionRegion() after the session starts. It returns "eu", "us", or null when no region was reported.

Meeting regions use eu, us-east, and us-west because they select the meeting bot location. A strict meeting invite also pins its engine session to the corresponding eu or us engine region.

Introduction

Personas

Security & Compliance

Resources

Session Regions

Request a region

Choose a region policy

Read the served region

​Request a region

​Choose a region policy

​Read the served region

Request a region

Choose a region policy

Read the served region