DOCSEARCHbyAlgolia
Submit Docs

Discord API Specification

repository·main·Indexed 43 days ago

https://github.com/discord/discord-api-spec

OpenAPI 3.1 specification for the Discord API (v10), providing machine-readable definitions of public endpoints, request/response schemas, and data models. Includes a stable spec (openapi.json) and a preview spec for experimental features (openapi_preview.json).

Tokens
560
Snippets
2
Records
4
Agent score
6%

What's inside Discord

  1. Understand Discord OpenAPI spec conventions

    main

    When consuming the Discord OpenAPI spec, be aware of the following implementation details and discrepancies:

    Union Types (anyOf vs oneOf)

    While the spec uses anyOf, it often behaves like a oneOf union. This means you must provide exactly one type from the list (e.g., Cat OR Dog, not both). This is explicitly marked with the custom extension x-discord-union: oneOf.

    Field Specification

    • Loose Constraints: The spec avoids over-specifying response fields. It defines types (like int32) but avoids defining specific minimums, maximums, or other constraints.
    • String vs Integer Types: Some fields documented as strings in the official Discord documentation may be typed as integers in the spec. The API accepts strings for integer fields if they are parseable as integers.

    Discrepancies

    If you find discrepancies between the OpenAPI spec and the official Discord developer documentation, follow the documentation, not the spec.

  2. Access the Discord OpenAPI Specification files

    main

    The repository provides two versions of the OpenAPI 3.1 specification for the Discord API (currently supporting v10):

    • openapi.json: The standard spec containing the stable, public API.
    • openapi_preview.json: The preview spec containing unstable and/or experimental API features. Warning: The preview spec is not stable and should not be used in production environments.

    ⚠️ Note: The public preview of the OpenAPI spec is subject to breaking changes without advance notice.

    specs/openapi.json
specs/openapi_preview.json

  4. Known limitations of the OpenAPI spec

    main

    The current OpenAPI specification has several known omissions and modeling quirks:

    • Missing Metadata: Operations and fields lack descriptions, and operations lack tags.
    • Flag Fields: Flag fields do not detail specific flag values or their meanings.
    • Nullable Types: Optional query arguments are typed as nullable, which may be semantically incorrect.