docs(api): expand API documentation to explain regional routing and regional domains

[dcramer]

Summary

The API docs currently have minimal, scattered coverage of Sentry's regional/multi-region architecture as it relates to API usage. The index.mdx "Choosing the Right API Base Domain" section and the data-storage-location page both exist, but neither explains the routing model clearly or gives developers enough context to use the API correctly across regions.

The goal of this issue is to expand the API docs so developers understand:

• What the regional domains (us.sentry.io, us2.sentry.io, de.sentry.io) are and why they exist
• That using the regional domain for your org is the recommended practice
• How to discover which regional domain applies to their organization
• That sentry.io/api continues to work for most API calls via the gateway, but the regional domain is preferred

Gap Analysis

1. The routing model is never explained

The docs say you can use a regional domain "if you want to indicate a specific data storage location" — framing it as optional. There's no explanation that Sentry operates a control plane (sentry.io) and regional cells (us.sentry.io, de.sentry.io), and that certain API resources live in the regional cell. Developers have no mental model for why the regional domain matters.

Where: docs/api/index.mdx — the existing "Choosing the Right API Base Domain" section needs a rewrite.

2. No explanation of which endpoint categories are regional vs. global

The docs link to the data-storage-location page for "what types of data are stored where", but that page is about data residency, not API routing. Developers can't easily map "I want to list issues" to "I need the regional domain."

At a high level, the docs should convey:

• Account-level resources (auth tokens, user settings, SSO, org metadata) → sentry.io
• Org/project/event data (issues, spans, replays, releases, etc.) → regional domain

3. No guidance on how to discover your regional domain programmatically

The docs only say "check your org settings page." Developers building integrations or CLIs need a programmatic path. The org details API response (GET /api/0/organizations/{slug}/) includes region information that could serve this purpose, but it's not documented here.

Where: needs a new sub-section or callout in docs/api/index.mdx.

4. Code examples use sentry.io without qualification

docs/api/auth.mdx, docs/api/requests.mdx, and the tutorial guides all use https://sentry.io/api/0/... in every curl example. For EU/non-US developers, this could lead to confusion if they expect latency benefits or are working with an endpoint that has regional implications.

Where: Examples throughout docs/api/ — at minimum, add a note explaining the base URL pattern and pointing to the routing section.

5. No dedicated "API regions and routing" reference page

The existing content is split between docs/api/index.mdx and docs/organization/data-storage-location/index.mdx. Neither page is titled or structured as a reference for API routing. A developer searching "which API domain should I use" or "Sentry API region" doesn't land in an obvious place.

Suggestion: Either expand docs/api/index.mdx significantly, or add a dedicated docs/api/regions.mdx page that covers this topic end-to-end, and link it from the API reference sidebar and from the data-storage-location page.

6. No guidance for tooling/CI use cases

Developers writing CI/CD pipelines or integrations often hardcode the base URL. There's no guidance like "to write region-agnostic code, resolve the org's regional domain at runtime via the API."

Proposed Content Outline

A new or significantly revised section/page should cover:

1. How Sentry's API is organized by region — brief conceptual explanation (control plane + regional cells)
2. When to use sentry.io vs. a regional domain — rule of thumb for account-level vs. org/data-level resources; note that sentry.io routes most calls correctly but the regional domain is preferred for reliability and latency
3. Regional domain reference table — already exists in data-storage-location, should be surfaced in the API docs directly
4. How to discover your org's regional domain — via the org settings UI and the /api/0/organizations/{slug}/ API response
5. Code example — show the pattern of resolving the base URL for an org before making data calls

Files to Update

• docs/api/index.mdx — expand or replace the "Choosing the Right API Base Domain" section
• docs/api/requests.mdx — add a note about the base URL and regional domains
• docs/api/auth.mdx — light callout near the curl examples
• docs/organization/data-storage-location/index.mdx — ensure the "Using Data Storage Location APIs" section links back to the API docs routing page
• Possibly add docs/api/regions.mdx as a dedicated page

--

View Junior Session in Sentry

[linear-code]

DOCS-2905

[dcramer]

fyi we're talking about making it so all calls work via the top level domain, but i think its important that theres still a clear handle on "requests are made this way" and how you fetch the regions (theres an endpoint), and then how you use them