# Document API Endpoint

Document and type a Sentry API endpoint.

- Repository: https://github.com/getsentry/skills (1107 stars)
- Category: Writing
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add getsentry/skills --skill document-api-endpoint -g -a claude-code -y`
Codex: `npx skills add getsentry/skills --skill document-api-endpoint -g -a codex -y`
Cursor: `npx skills add getsentry/skills --skill document-api-endpoint -g -a cursor -y`
Gemini CLI: `npx skills add getsentry/skills --skill document-api-endpoint -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add getsentry/skills`

## Description

Document and type a Sentry API endpoint. Write or fix @extend_schema decorators, specify response TypedDicts, type request parameters, correct type drift between the declared schema and the runtime response, and validate the generated spec. Use when asked to "document an endpoint", "add OpenAPI docs", "add/fix @extend_schema", "type an endpoint response", "fix the response type", "fix type drift", "reuse a response type", "split an overloaded endpoint", "specify the response schema", "add a TypedDict response", "migrate a legacy api-docs path", "fix a parameter type", or "make an endpoint public" / "promote an endpoint" (promotion is one section here).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Document & Type a Sentry API Endpoint

Add or fix OpenAPI docs for a Sentry endpoint with drf-spectacular. Full reference is at https://develop.sentry.dev/backend/api/public/, the most useful section to you will be https://develop.sentry.dev/backend/api/public/#5-method-decorator. This skill captures the non-obvious lessons on top of it. Most of the work is making the declared schema match what the endpoint actually returns. Before documenting, identify which endpoint class serves the route and what it does; the MCP tool that calls it is usually the fastest way to confirm its behavior. Promoting a PRIVATE/EXPERIMENTAL endpoint to PUBLIC is one application (see below).

## Workflow

1. Class-level `@extend_schema(tags=[...])`, use the closest existing `OPENAPI_TAGS` entry.
2. Method-level `@extend_schema(operation_id=..., parameters=[...], responses={...}, examples=...)`.
3. Reuse `src/sentry/apidocs/parameters.py` and `examples/*.py`; ensure `owner = ApiOwner.<TEAM>` is set.
4. If a legacy `api-docs/paths/**/*.json` covers the path, remove it (see lesson 4).
5. Validate, then verify against the live endpoint (lesson 1).

## Lessons

### 1. Carefully compare what the code does vs declared types
Ideally, hit the live endpoint with a real token and diff the keys and types against your TypedDict. Serializers are sometimes inaccurate. Look out for counts coming back as floats instead of integers, IDs declared `int` emitted as strings, nested types declaring the wrong number of fields. Correct the declared type to match runtime.
```bash
curl -s -H "Authorization: Bearer $TOKEN" "https://us.sentry.io/api/0/<endpoint>" | jq 'keys'
```

The rest: https://github.com/getsentry/skills/blob/HEAD/skills/document-api-endpoint/SKILL.md