# Regional policy (/guides/regional-policy)



A regional policy pins where a project's traffic is allowed to execute. Zumik defaults to US regions;
set a policy to require EU-only, US-only, or a custom allow-list, and the
[Execution Broker](/concepts/execution-profiles) enforces it before dispatching to any provider. A
request that would resolve to a region your policy forbids is rejected, not silently re-routed.

## Set a policy [#set-a-policy]

`PUT /v2/governance/regional-policy`. The body declares a `region_policy` shorthand, an optional
explicit `allowed_regions` list, and a `data_boundary`.

| Field             | Type      | Notes                                                                         |
| ----------------- | --------- | ----------------------------------------------------------------------------- |
| `region_policy`   | string    | Shorthand: `us_only`, `eu_only`, or `global`/`any` for no restriction.        |
| `allowed_regions` | string\[] | Optional explicit allow-list, combined with the shorthand. Defaults to empty. |
| `data_boundary`   | string    | How far data may travel for execution. Defaults to `project`.                 |

```bash
curl -X PUT https://api.zumik.ai/v2/governance/regional-policy \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "region_policy": "eu_only",
    "allowed_regions": ["eu"],
    "data_boundary": "project"
  }'
```

```json title="Response"
{
  "id": "rgp_01jy…",
  "object": "regional_policy",
  "project_id": "prj_01jy…",
  "region_policy": "eu_only",
  "allowed_regions": ["eu"],
  "data_boundary": "project",
  "updated_at": "2026-06-15T12:00:00Z"
}
```

Read the current policy with `GET /v2/governance/regional-policy`. The update is written to the project
audit log.

<Note>
  A `global`/`any` policy - or no policy at all - imposes no region restriction. To constrain
  execution, set a concrete shorthand or a non-empty `allowed_regions` list.
</Note>

## How allowed regions resolve [#how-allowed-regions-resolve]

The broker flattens your policy into a concrete lowercase allow-list. The `region_policy` shorthand
contributes a region (`us_only`/`us` -> `us`, `eu_only`/`eu` -> `eu`), `allowed_regions` are added
verbatim (lowercased), and `global`/`any`/empty contributes nothing. The combined list is deduped and
sorted. When the list is empty, the project has no restriction; when it is non-empty, the resolved
region for a request must appear in it.

## Enforcement returns region\_not\_allowed [#enforcement-returns-region_not_allowed]

On each request the broker resolves the provider, derives its region, and checks it against the
flattened allow-list. If the region is not permitted, the request is rejected **before** any provider
call - so no data leaves an allowed region and you are not charged:

```json
{
  "error": {
    "message": "Resolved region 'us' is not permitted by this project's regional policy.",
    "type": "invalid_request_error",
    "code": "region_not_allowed"
  }
}
```

The status is `403` - a clear policy denial, distinct from a `401` missing-key or a `429` quota error.
On `/v2`, a request blocked by region can also surface in the [QoS outcome](/guides/qos-outcomes) with
`reason_code: "region_unavailable"` when no allowed region could serve it. On `/v1`, the same `403`
error body is returned, keeping the envelope OpenAI-shaped.

<Warning>
  Regional policy gates the *resolved* region. If your allow-list excludes the only region a model's
  provider runs in, every request for that model is rejected. Pair a tight region policy with an
  [alias](/concepts/model-aliases) whose targets actually run in an allowed region.
</Warning>

<CardGroup cols="2">
  <Card title="Data privacy and retention" icon="shield-halved" href="/security/data-privacy-and-retention">
    Default US residency, trace modes, and how data boundaries map to retention.
  </Card>

  <Card title="GDPR and CCPA" icon="scale-balanced" href="/security/gdpr-ccpa">
    Configuring EU residency and the data-subject-rights flows.
  </Card>
</CardGroup>