docs: add operation descriptions and typed error bodies to the OpenAPI spec

[shirgoldbird]

Spec-only changes, from an audit of how machine-readable our API surface is. No behavior claims beyond what the live API already does, but points 2 and 3 assert things about the API's error contract, so they want a review from someone who owns that contract.

Precedent: #366 ("fix(openapi): add response body to generic error responses", merged 2026-06-08) did exactly this for 7 shared error responses — BadRequest, Unauthorized, Forbidden, NotFound, PayloadTooLarge, TooManyRequests, QuotaExceeded — for the same reason. Point 2 below covers the 6 that PR left behind, so most of this change is following that precedent rather than setting new policy. Point 3 is the one genuinely new judgment call.

1. description on 27 operations

27 of 62 operations had only a summary. Anything that generates a client or a tool definition from the spec had nothing to work from for those endpoints.

2. A JSON schema on every error response

141 error responses declared only a description and no content. Reading the spec, a client could not tell that DeepL returns a parseable JSON body on an error at all.

Fixed at the source rather than per-operation, continuing #366: 6 shared components/responses (InternalServerError, ServiceUnavailable, ForbiddenGlossaries, URITooLong, UnsupportedMediaTypeGlossaries, QuotaExceededGlossaries) now declare application/json, and two inline 415s now $ref the shared UnsupportedMediaType response instead of duplicating it.

3. InfrastructureErrorResponse, with oneOf on 414/500/503/504

While probing the live API I found the edge layer returns a different error shape than the application:

$ curl 'https://api.deepl.com/v2/languages?type=<9000 chars>'
HTTP/2 502
{"error": {"message": "Bad Gateway."}}

versus the application's {"message": "..."}. So declaring only ErrorResponse on the codes that either layer can produce would have been wrong. Those four now use oneOf: [ErrorResponse, InfrastructureErrorResponse].

This is the part #366 did not have to decide, since the codes it touched are all application-level.

Questions for the reviewer

1. Is the oneOf split on 414/500/503/504 right? I mapped the two shapes by observation. Someone who knows which layer serves which status code should confirm, especially for 503/504.
2. HTTP 502 is undocumented. It appears in no operation's responses, but the edge clearly returns it. Adding it across 62 operations is a call on what the edge guarantees, so I left it out.
3. New operation descriptions are worth a skim for accuracy, particularly the Admin API and Style Rules ones.
4. POST /v2/glossaries (v2) got "For new integrations we recommend POST /v3/glossaries" rather than any deprecation wording, per CLAUDE.md. Flagging in case a stronger signal is wanted.

Verification

• openapi.json regenerated with yq -o=json, verified structurally identical to the YAML.
• mint broken-links --check-anchors: same finding count before and after, all pre-existing (pipeline/drafts/ and existing anchor drift).
• mint dev: all API reference pages still render, new descriptions confirmed on the rendered pages.
• Rebased onto main on 2026-09-09 to pick up the six intervening openapi.yaml changes (Voice French variants, hr/tl translated speech, glossary term-matching limits). Clean rebase, no conflicts; the only removed lines in the diff are the two inline 415 descriptions replaced by the $ref.

Note

openapi.yaml also lives in the openapi repo. These changes still need porting there. (sync-openapi-specs.yml runs on push to main and may handle this automatically — worth confirming on merge.)

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
deepl-c950b784	🟢 Ready	View Preview	Sep 9, 2026, 2:34 PM

💡 Tip: Enable Automations to automatically generate PRs for you.