From ca477d2ba96dcc98ce6ca75aced39c2f446abebc Mon Sep 17 00:00:00 2001
From: youdie006 <youdie006@users.noreply.github.com>
Date: Mon, 6 Jul 2026 16:22:38 +0900
Subject: [PATCH] docs(api): explain regional routing and regional domains

Document the global vs region-specific domain model, the regional domains,
and how to look up an organization's region programmatically.
---
 docs/api/index.mdx                            | 50 ++++++++++++++++---
 .../data-storage-location/index.mdx           |  2 +
 2 files changed, 44 insertions(+), 8 deletions(-)

diff --git a/docs/api/index.mdx b/docs/api/index.mdx
index a0e805f7e8784..209b89b47163d 100644
--- a/docs/api/index.mdx
+++ b/docs/api/index.mdx
@@ -26,14 +26,48 @@ The current version of the Sentry's web API is considered **v0**. Our public end
 
 ## Choosing the Right API Base Domain
 
-While many of Sentry's APIs use `sentry.io` as the host for API endpoints, if you want to indicate a specific [data storage location](/organization/data-storage-location/#what-types-of-data-are-stored-where), you can use your region-specific domain.
-Using your organization's region-specific domain will generally result in lower latency for most API calls. For example, if you are hosted in US2 region, you would use `us2.sentry.io`. You can check which region your organization is in by viewing your organization’s settings page.
+Sentry's API is served from two kinds of hosts:
 
-- US region is hosted on `us.sentry.io`
-- US2 region is hosted on `us2.sentry.io`
-- DE region is hosted on `de.sentry.io`.
+- `sentry.io` is the global domain. It serves account-level resources that are shared across your organizations, such as user settings, authentication tokens, and organization metadata.
+- Region-specific domains, such as `us.sentry.io` and `de.sentry.io`, serve the data that belongs to a single organization, such as issues, events, spans, releases, and replays. This data lives in the [region you selected](/organization/data-storage-location/) when the organization was created.
 
-To find out which API resources are available on region-based domains, see [what
-types of data are stored
-where](/organization/data-storage-location/#what-types-of-data-are-stored-where) for more information.
+Requests to `sentry.io` are routed to the correct region for you, so existing integrations keep working. For requests that read or write an organization's data, we recommend sending them directly to that organization's region-specific domain. This is the recommended practice and generally results in lower latency.
+
+As a rule of thumb:
+
+- Use `sentry.io` for **account-level resources** — authentication tokens, user settings, SSO configuration, and organization metadata.
+- Use your organization's **region-specific domain** for **organization data** — issues, events, spans, profiles, logs, metrics, releases, and replays.
+
+To see exactly which resources live in a region versus on the global domain, see [what types of data are stored where](/organization/data-storage-location/#what-types-of-data-are-stored-where).
+
+### Regional Domains
+
+| Region | API domain      |
+| ------ | --------------- |
+| US     | `us.sentry.io`  |
+| US2    | `us2.sentry.io` |
+| EU     | `de.sentry.io`  |
+
+You can check which region your organization is in by viewing your organization’s settings page.
+
+### Finding Your Organization's Region Programmatically
+
+If you're building an integration, CLI, or CI job, resolve the region at runtime instead of hardcoding a domain. Request the list of regions the authenticated user belongs to:
+
+```bash
+curl -H 'Authorization: Bearer <auth_token>' https://sentry.io/api/0/users/me/regions/
+```
+
+The response lists each region the user has organizations in, along with the base URL to use for that region. For example:
+
+```json
+{
+  "regions": [
+    { "name": "us", "url": "https://us.sentry.io" },
+    { "name": "de", "url": "https://de.sentry.io" }
+  ]
+}
+```
+
+Use the `url` value as the base domain for that organization's subsequent data requests. The organization details endpoint, `GET /api/0/organizations/{organization_slug}/`, also returns the region an individual organization belongs to.
 
diff --git a/docs/organization/data-storage-location/index.mdx b/docs/organization/data-storage-location/index.mdx
index 2341d55020f71..51a40690b7a22 100644
--- a/docs/organization/data-storage-location/index.mdx
+++ b/docs/organization/data-storage-location/index.mdx
@@ -86,6 +86,8 @@ To ensure that your API requests are only processed within your selected data st
 
 For [data stored in the US](#data-stored-in-us), your API domain should be `sentry.io`.
 
+For more on how the Sentry API routes requests by region, when to use `sentry.io` versus a region-specific domain, and how to discover your organization's region programmatically, see [Choosing the Right API Base Domain](/api/#choosing-the-right-api-base-domain) in the API reference.
+
 ## Switching Data Storage Locations for Existing Organizations
 
 ### SaaS