Index of every page on this site: llms.txt
All skills
getsentry avatar

/document-api-endpoint

@a582c51 official
by Sentrygetsentry/skills1.2k stars
71
Run it yourself

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).

Use this Skill: https://skilld.dev/gh/getsentry/skills/document-api-endpoint

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈171 tokens for metadata: the name and description. ≈960 when used: this file.

Description uses 8.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈684 characters, or 8.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

curl -s -H "Authorization: Bearer $TOKEN" "https://us.sentry.io/api/0/<endpoint>" | jq 'keys'

2. Reuse the canonical response type

Match the codebase's XxxResponseOptional(TypedDict, total=False) mixin (main class declares required fields). Nullable-vs-absent: T | None = key always present, value may be null; NotRequired[T] = key only set under a condition (e.g. an expand query param). Reuse the existing canonical type instead of re-declaring a second or third copy in a *_types.py. If there's no clean canonical type to reuse (e.g. a payload proxied from another service like vroom/profiling), type it dict[str, Any] rather than inventing a new mirror, and confirm the shape from the owning service's repo, not just the serializer.

3. Infer the type. Avoid cast and # type: ignore

When a serializer returns a base type plus extra fields, refactor the producing code so the response type is inferred rather than forced.

4. Legacy doc migration is all-or-nothing per path

Delete the api-docs/paths/**/*.json file AND its $ref in api-docs/openapi.json. drf-spectacular's APPEND_PATHS does not merge HTTP methods, so once any method on a path uses @extend_schema, all legacy methods on that path vanish — migrate every method on the path in one commit.

Promoting to PUBLIC

Do the workflow above, then on the concrete endpoint only (leave siblings PRIVATE):

  • Bump publish_status[<METHOD>] → PUBLIC and set owner = ApiOwner.<TEAM>.
  • Remove the method from API_OWNERSHIP_ALLOWLIST_DONT_MODIFY in the same change as the flip.
  • If the endpoint is redundant or being renamed, delete or deprecate the old version in its own change first, then stack the publish on top.
  • Note in the PR if scopes widen (event:read → event:{admin,read,write}) — that's drf-spectacular regenerating from permission_classes, documentation-only.

The change reaches the @sentry/api SDK / MCP with the next api@ release of getsentry/sentry's static/packages/api, which openapi.yml cuts on master when the spec changes.

Validate

make build-api-docs
pnpm run validate-api-examples
.venv/bin/pytest -q --reuse-db tests/apidocs/endpoints/<area>/test_<name>.py
.venv/bin/prek run -q --files <changed paths>

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts4d3 checks · Risk SAFE
  • Gen Agent Trust Hub5d

    This skill provides a comprehensive guide for documenting Sentry API endpoints. It instructions on using the drf-spectacular library, managing response types, and following established vendor workflows. All external references and commands point to official Sentry infrastructure or standard developer tooling.

  • Socket4d

    No alerts

  • Snyk5d

    Risk: LOW · No issues

Signed by skilld at a582c51. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last week
  • TypeScript
  • Python
  • openapi
  • sentry
  • drf-spectacular
  • api-documentation
  • rest-api
  • schema-validation

README badge

README badge for getsentry/skills/document-api-endpoint

Adds or fixes OpenAPI documentation for Sentry API endpoints using drf-spectacular, including @extend_schema decorators, TypedDict response types, and parameter typing. Use when documenting an endpoint, fixing type drift between declared schema and runtime response, or promoting a PRIVATE endpoint to PUBLIC.

Generated from the current SKILL.md.

What does @extend_schema do and where do I use it?
The @extend_schema decorator from drf-spectacular documents API endpoints for OpenAPI. Use it at the class level to set tags, and at the method level to specify operation_id, parameters, response types, and examples.
How do I know if the declared response type matches what the endpoint actually returns?
Hit the live endpoint with a real token using curl and jq to inspect the actual response keys and types, then compare them against your TypedDict. Check for type drift like counts as floats instead of integers or IDs as strings instead of ints.
Should I create a new TypedDict or reuse an existing response type?
Reuse the canonical response type already in the codebase (e.g. XxxResponseOptional). If no clean canonical type exists, use dict[str, Any] instead of inventing a new mirror type.
If I document one HTTP method on a path that had legacy api-docs/paths JSON, what happens to the other methods?
Once any method on a path uses @extend_schema, all legacy JSON docs for that path vanish. You must migrate every method on the path in a single commit and delete the corresponding api-docs/paths/*.json file.
What's the process for promoting a PRIVATE endpoint to PUBLIC?
Change publish_status[<METHOD>] to PUBLIC, set owner = ApiOwner.<TEAM>, and remove the method from API_OWNERSHIP_ALLOWLIST_DONT_MODIFY. The change reaches the @sentry/api SDK only after sentry-api-schema regenerates downstream.

Generated from the current SKILL.md. These answers refresh after source changes.