discord-api-types keeps Discord typings pinned to an API version

The import path is the API version

The design decision that defines this package is that there is no default export. You can only import the module by specifying the API version you want to target, by appending /v* to the import path where the star represents the version.

const { APIUser } = require('discord-api-types/v10');

// TypeScript/ES Module support
import { APIUser } from 'discord-api-types/v10';

That constraint does more work than it looks. Discord versions its API, and different API versions mean different payload shapes for the same logical object. A library that shipped one set of types would force every consumer onto one version and would break every time the platform changed something. By making the version part of the path, two projects can depend on the same package and target different API versions at the same time, and your import statement is the record of which one you chose. The repository reflects this directly, with top level entry files for v6, v8, v9 and v10 and matching directories for gateway, payloads, rest, rpc and utils under each version. Nothing is deprecated at the type level. You keep targeting v9 for as long as you need to, and the compiler keeps telling you the truth about v9.

Subpath imports let you pull in one slice of the API

Beyond the version subpath, the package exposes named slices that you can import on their own. The possible values are globals, gateway, gateway/v*, payloads, payloads/v*, rest, rest/v*, rpc, rpc/v*, utils, utils/v* and voice, plus voice/v*. A project that only handles gateway events does not need to load the REST route types, and the import path lets it say so.

const { GatewayVersion } = require('discord-api-types/gateway/v10');

// TypeScript/ES Module support
import { GatewayVersion } from 'discord-api-types/gateway/v10';

There is a note about how the version level exports compose. The v* exports include the appropriate version of gateway, payloads, rest, rpc and utils that you specified, alongside the globals exports. So discord-api-types/v10 is the umbrella entry for a whole API version, and discord-api-types/gateway/v10 is the narrow one. The package manifest encodes both shapes in the exports map, and each entry carries a types path alongside require and import paths, so a CommonJS consumer and an ESM consumer get the same definitions and the type declarations resolve for both. The voice subpath exists as a separate slice with its own versioned form, which tells you the package treats voice as a distinct area of the API rather than folding it into the gateway types.

Three naming conventions that let you predict a type

The exported names follow conventions detailed in the project structure section, and once you know them you can guess what a type is called before you look it up. Everything exported with the API prefix represents a payload you may get from the REST API or the Gateway. Everything with the Gateway prefix represents data that only comes from or is directly related to the Gateway. Everything with the REST prefix represents data that only comes from or is directly related to the REST API. Anything else is miscellaneous and is exported based on what it represents, for example the REST route object.

The REST naming is the most elaborate and the most useful to know. Endpoint option types follow the structure REST<HTTP Method><Type><Query|(JSON|FormData)Body|Result>, where the type represents what the call returns. Two examples given are RESTPostAPIChannelMessageJSONBody and RESTGetAPIGatewayBotInfoResult. OAuth2 related types are the documented exception, since they start with either RESTOAuth2 or something similar to REST<HTTP Method>OAuth2, because the nature of those fields does not fit the general shape. If a type ends with Result it represents the expected result of calling its accompanying route, and a result that will be a 204 No Content is typed as undefined, which the documentation is careful to add does not account for errors. That last caveat is a good example of the package being precise about the limits of what a type can promise.

What gets typed and what deliberately does not

The scope of the types is bounded by an explicit policy, and this is the part of the documentation most worth reading before you rely on a field. The package adds types only for known and documented properties present in Discord's API Documentation repository, that are mentioned in an open pull request, or that are known through other means and have received the green light to be used. Anything else will not be documented, and the documentation gives client only types as the example. In practice that means you should not expect to find a type for something the platform itself has not documented, and if you were hoping to use a field that exists only inside Discord's own client code, it is not here.

There is a narrow escape hatch. Certain types that are not in the API Documentation repository may be allowed on a case by case basis, and those are documented with an @unstable tag. The rule attached to that tag is that they are not subject to the same versioning rules. That is worth internalising, because it means an @unstable type can change or disappear between patch releases of the package without the version guarantees that the rest of the API carries. Types that are identical across all versions are exported as they are and can be found in the globals file, still prefixed according to the same rules, so the naming convention holds even for the version independent part.

Installing on npm, pnpm, yarn, bun and Deno

Installation is a single dependency, and the project documents four package managers side by side.

npm install discord-api-types
pnpm add discord-api-types
yarn add discord-api-types
bun add discord-api-types

Deno is supported through three import routes rather than a package manager. You can pull a file straight from GitHub, targeting a specific API version.

// Importing a specific API version
import { APIUser } from 'https://raw.githubusercontent.com/discordjs/discord-api-types/main/deno/v10.ts';

The second route is deno.land/x, and the third is skypack.dev with the dts query parameter. The GitHub route points at the main branch rather than a release tag, which means a Deno project consuming that URL is tracking the branch and will see whatever changes land there, while the deno.land and skypack routes resolve to published versions. That distinction is easy to miss and matters if you want reproducible builds. The repository also carries a deno directory and the website lives under website/, with a homepage at discord-api-types.dev.

Release cadence and what a patch bump means

The version numbers tell the story of how this package evolves. The recent releases are 0.38.57 on 2026-10-19, 0.38.56 on 2026-09-28 and 0.38.55 on 2026-09-02, and the last push to the repository was on 2026-10-22. A project version that reads as 0.38.x rather than 1.x or 2.x, combined with releases that land every few weeks, is the profile of a package that tracks an external API and adjusts to it, rather than one that ships large features of its own. For a consumer, that means a patch upgrade is cheap and usually about Discord changing something, and it also means the lockfile matters more than usual, because the package's own behaviour depends on the state of Discord's documentation at the moment it was published.

The tooling around those releases is visible in the repository. renovate.json sits at the top level for dependency updates, there is a husky directory for git hooks, an eslint config written in TypeScript, a pnpm workspace file, an api-extractor.json for API surface reporting, a tsdoc.json for documentation processing and a scripts directory. The licence is MIT, so the definitions carry the usual attribution condition and no copyleft obligation, which is the licence you want in a package that other libraries vendor into their own type definitions.

What this package does not do for you

It is worth being blunt about the boundary, because a types-only package attracts expectations it cannot meet. discord-api-types contains no HTTP client, no gateway connection, no rate limit handling and no authentication logic. It does not fetch anything and it does not validate at runtime. If you install it and then look for a way to send a message, you will not find one, because that is a different package with a different job. The runtime behaviour of a Discord API call, including what the server actually returns when it disagrees with the docs, is outside what a compile time type can tell you.

The other limit is the version boundary. You are pinned to the version you import, which is the feature, but it is also a maintenance obligation. When Discord ships a new API version, you have to move to the new subpath and resolve whatever type errors that surfaces. That migration is the cost of the guarantee, and the reason the version is explicit rather than hidden. A library that wanted to abstract over versions would need a compatibility layer that could not promise per-version field accuracy, which is the trade this package refuses to make. If you want both a current API and a stable type surface, you would maintain that abstraction yourself on top of one version, which is a reasonable pattern but not one the package provides.

Editorial conclusion

Adopt discord-api-types if you build Discord bots or libraries in TypeScript and want the payload and route types checked at compile time against a specific API version. Do not adopt it if you need undocumented fields, since the package documents only properties that appear in Discord's API documentation repository, are mentioned in an open pull request, or are otherwise known and approved, and client only types are left out entirely. Verify two things first: that the API version you import matches the one your bot actually speaks at runtime, since a mismatch type-checks cleanly against the wrong shape, and that any type you rely on is not tagged @unstable, because those are not subject to the same versioning rules. The practical first step is to add the package, import a single payload type from the version subpath you need, and let your compiler point at every call site whose shape the newer version changed.

Frequently asked questions

Official sources

1. discordjs/discord-api-types on GitHub
2. License: MIT
3. Project website
4. README
5. Releases