feat(api): Add a PUBLIC_EXPERIMENTAL publish status

[DominikB2014]

Adds PUBLIC_EXPERIMENTAL to ApiPublishStatus, filling the gap between an endpoint being invisible and being frozen under a permanent stability commitment — it is published, but free to change incompatibly. Publication is now expressed once as ApiPublishStatus.is_published, and every gate that keyed on PUBLIC reads it (the OpenAPI filter, the S022 response-shape lint, and the Seer public-API matrix), so the new status clears the exact same documentation bar as PUBLIC rather than offering a shortcut past it. Because nothing downstream renders the x-sentry-experimental marker these operations now carry, the build also prepends a short notice to the rendered description — four endpoints were already hand-writing that warning into their docstrings in four different wordings, one of them buried at the end, and this standardizes on the most common of them. The trace-items/metrics endpoint adopts the status as the first user: publishing it pulls it into the Seer matrix, which needs its feature flag registered there, and it gains a response example, with its response TypedDicts moving to a *_types.py so the examples module can import them without a circular import. Follow-ups: a sentry-docs badge reading x-sentry-experimental to replace the text notice, the Sentaur bot tolerating the new public_experimental key in the ownership stats JSON, and migrating those four hand-rolled endpoints onto the status.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e15807c. Configure here.}

[cursor]

Seer matrix missing metrics query mock

Medium Severity

Publishing OrganizationTraceItemMetricsEndpoint pulls it into the Seer public-API matrix, and the feature flag was registered so the request no longer 404s. The matrix still has no downstream mock for TraceMetrics.run_table_query, unlike the sibling EAP endpoints, so the baseline GET is likely to 500 instead of the required 200.

Additional Locations (1)

• tests/sentry/seer/endpoints/test_organization_agent_token.py#L1285-L1286

 

^{Reviewed by Cursor Bugbot for commit e15807c. Configure here.}