discord/discord-api-docs: the official API reference as a contribution target

What discord-api-docs actually is, and who edits it

This is not a client library. It is the source of the official Discord for Developers documentation, written in MDX and published at docs.discord.com/developers. The README describes it as the documentation "as it is meant to be accessed by third-party applications", and adds that it omits features and capabilities that are not generally available or not fully supported for third-party usage. That sentence is the most important thing on the page. The published reference is deliberately narrower than the platform Discord runs internally.

The audience is therefore narrow too. If you maintain a Discord library, write bots against endpoints you looked up here, or want to correct an example that is wrong, this repository is where that happens. The README points contributors at three separate channels: the issue tracker for API bugs, Discussions for feature and improvement requests, and pull requests for documentation changes, with CONTRIBUTING.md governing which changes are accepted and the markdown syntax used.

If you arrived looking for an SDK to install, you are in the wrong repository. There is nothing here to import.

How the documentation repository is built

The repository is a Node workspace, not a single package. package.json sets "private": true, requires Node >= 20.11.0, and declares one workspace, tools. The scripts are thin wrappers: lint runs the table tests and linter inside tools, lint:fix does the same in fix mode, and build delegates to tools. So the validation logic lives under tools/, and the root package.json is mostly a dispatcher.

Two other pieces of the layout matter. docs.json at the top level is the Mintlify site configuration, and developers/ holds the MDX content that becomes the published pages. Snippets, styles, images and resources sit alongside them. Husky and lint-staged are wired up through a prepare script, and lint-staged runs lint:fix on markdown and MDX files and runs lint:fix plus build on TypeScript, JavaScript and JSON files. In practice that means a commit touching a table or a code sample triggers the same checks CI would, before the commit lands.

The linting stack is not incidental. .vale.ini and a vale/ directory indicate prose linting on top of the structural checks, which is unusual for a docs repository and tells you style is treated as part of correctness here.

Installing Mintlify and previewing a change

The README gives the local preview path directly. Install the Mintlify CLI globally with npm, then run the dev server from the repository root. The README notes your browser should open automatically; if it does not, the target is http://localhost:3000/developers/intro.

npm i -g mintlify

From the root of a clone, start the preview server:

mintlify dev

Node 20.11.0 or newer is required by the repository's engines field, so check that before anything else. The repository also declares a prepare script that runs husky, and lint-staged is configured through the root package.json. If you want to run the checks the project uses rather than only the preview server:

npm run lint

That command runs the table tests and the linter inside the tools workspace. What you should see is the preview site served locally with your MDX edits applied, and, for the lint command, output from the tools workspace rather than the root.

The repository is a mirror of what Discord has released

The clearest limitation is stated by the project itself. The README says the repository reflects the Discord Developer Platform as it is meant to be accessed by third-party applications, and that it omits features and capabilities that are not generally available or not fully supported for third-party usage. If you are debugging an endpoint that exists but is undocumented, this repository will not help, and no amount of reading it will tell you whether the omission is deliberate or an oversight.

The release history reinforces that this is a documentation set rather than a versioned product. The only release listed is legacy-gamesdk, dated 2024-08-02, which is a docs snapshot for a legacy GameSDK. There is no semantic version stream to pin against. If you vendor these pages into your own product, you are tracking a moving branch, and the push history is the only signal of how current your copy is.

A second constraint is structural: because the checks run through a Node workspace with Husky hooks, contributing from an environment without Node 20.11.0 or newer means the tooling will not run as configured, even though editing MDX itself needs no compiler.

Where this fits against a generated API reference

A common alternative is a reference generated from an OpenAPI or protobuf definition, where the published page is a rendering of a machine-readable contract and the prose is minimal. The difference in approach is real. A generated reference cannot fall out of sync with the schema, but it also cannot explain intent, warn about rate-limit behaviour in a sentence, or tell you which of two similar endpoints a third-party application should use.

This repository takes the opposite position. The content is hand-written MDX, the site configuration is docs.json, and correctness is enforced by linters and table tests rather than by a schema diff. That buys explanatory prose and curated examples at the cost of a manual review step for every change, which is why CONTRIBUTING.md exists and why the README asks contributors to read it fully before opening a pull request.

Neither approach is strictly better. If you need a contract to generate client code from, a schema-derived reference is the right tool and this repository is not. If you need to know what Discord intends an endpoint to be used for, the generated reference usually will not say.

Licence terms for reusing the text and the samples

The licensing split is explicit. The README states that, except as otherwise noted, the Discord API Documentation and other content in the repository is licensed under Creative Commons Attribution-ShareAlike 4.0, with the LICENSE file at the root, while code samples are licensed under the MIT License, with LICENSE-CODE. The ShareAlike term on the prose is the part that catches people out: reusing documentation text carries an attribution and share-alike obligation that the MIT-licensed samples do not.

There is a second boundary the README draws. These licences do not grant rights to use Discord's trademarks or other brand features, and it points to the Discord Developer Terms of Service for that. So the open licence on the text does not extend to the branding around it. This is a description of what the repository says, not legal advice; if you plan to redistribute the documentation inside a commercial product, read LICENSE, LICENSE-CODE and the Developer Terms yourself.

Maintenance signals in the repository

The repository is not archived, and the last push was on 2026-09-21. That is a single day before the date used to judge recency here, so the branch is being updated. The absence of numbered releases does not contradict that; it reflects the fact that documentation changes ship as commits rather than as tagged versions.

What this means for a consumer is limited. There is no changelog file listed at the top level and no release feed to subscribe to, so the practical way to track changes is to watch the repository or diff your vendored copy against main. The presence of Husky, lint-staged and a Vale configuration suggests changes go through automated checks before merge, which reduces the chance of a broken table or a malformed example reaching the published site, but it says nothing about how quickly an undocumented endpoint will be documented.

Editorial conclusion

Adopt this repository if you are writing or correcting Discord API documentation: the contribution path is a pull request against MDX files, and the local preview is two commands. Do not treat it as a library, an SDK or a versioned release artefact, and do not expect it to document anything Discord has not made generally available to third-party applications, because the README states the repository omits those capabilities. Before your first pull request, read CONTRIBUTING.md in full, as the README instructs, and run mintlify dev to confirm your change renders at http://localhost:3000/developers/intro. For anything you ship commercially, check the split between the CC-BY-SA-4.0 documentation licence and the MIT code-sample licence in LICENSE and LICENSE-CODE first.

Frequently asked questions

Official sources

1. discord/discord-api-docs on GitHub
2. License: CC-BY-SA-4.0
3. Project website
4. README
5. Releases