Discord's API Is Preparing for More Flag Bits

A small field change in an API can have a surprisingly big impact on developers.

Discord's Application object now includes flags_new, a string serialized integer that carries the full set of application flag bits. It addresses a limitation in the existing flags field, which cannot grow beyond 31 bits.

The distinction matters because application flags are used to represent properties and capabilities associated with Discord applications. As additional flag bits are introduced, the API needs a way to represent them without exceeding the limits of the older numeric representation.

Discord's official Application Resource documentation explains the change directly: new flag bits beyond bit 30 will appear in flags_new, while existing integrations consuming flags are not impacted.

For developers, this is not a complete replacement of the old field. It is an extension designed to accommodate future growth while preserving compatibility.

🧠 What Exactly Is flags_new?

To understand the change, it helps to understand how flags work.

An application flag is part of a bit field. Each flag corresponds to a particular bit position, and multiple flags can be combined into a single integer.

For example, Discord documents application flags associated with capabilities and requirements such as gateway presence, guild member access, message content access, and application command badges.

The existing flags field represents these flags as a number. However, that representation is limited to 31 bits.

The new flags_new field is a string containing the full integer representation of the application's flag bits.

This distinction is documented in Discord's Application Resource reference.

The important point is that flags_new does not introduce an entirely new flag system. It provides a representation that can accommodate higher bit positions.

⚙️ Why Bits Beyond Bit 30 Matter

Bit positions are commonly represented using powers of two.

The value of bit 30 is:

The next position, bit 31, has a value of:

As flag systems expand, new flags may require positions beyond bit 30. A numeric field constrained to the legacy representation cannot carry those new bits in the same way.

That is the problem flags_new addresses.

Rather than forcing the legacy flags field to grow beyond its documented limit, Discord can serialize the complete integer as a string.

For API consumers, the string representation also helps avoid precision problems in languages where ordinary numeric types cannot safely represent arbitrarily large integers.

The benefit is straightforward: Discord can introduce higher application flag bits without requiring the old numeric field to expand beyond its established limit.

💻 What Does the API Response Look Like?

An Application object can contain both fields in the same response.

For example, a simplified response could look like this:

{
  "id": "123456789012345678",
  "name": "Example Application",
  "flags": 8192,
  "flags_new": "8192"
}

This example illustrates the serialization format, not a specific application's real flags.

Notice that flags is a JSON number, while flags_new is a JSON string. Both represent the same value in this example.

When higher bits are present, flags_new can represent the complete integer without being restricted to the legacy field's 31 bit limit.

Discord's documentation also makes an important distinction: flags_new is intended for response serialization only. Developers should continue using the original flags field when making requests to endpoints that accept flag values.

🔍 How Existing Discord Bots Are Affected

The compatibility message is one of the most important parts of this update.

Discord explicitly states that existing integrations consuming flags are not impacted by the introduction of flags_new.

If your bot or integration reads existing application flags that fit within the legacy representation, you do not need to replace every use of flags simply because the new field exists.

However, developers building new integrations or updating API libraries should understand which field to read.

A sensible approach is:

1. Continue using flags for existing functionality that relies on the legacy field.

2. Read flags_new when your application needs the full set of application flag bits.

3. Parse the string with an integer representation that safely supports the values your language may encounter.

4. Continue sending flags in requests where Discord expects that field.

This avoids unnecessary changes to working integrations while making new code ready for higher flag positions.

⚠️ JavaScript Developers Should Pay Attention to Integer Precision

JavaScript developers should be especially careful when working with the full integer string.

The standard JavaScript Number type cannot represent every integer exactly beyond Number.MAX_SAFE_INTEGER.

If future flag values exceed that safe range, converting flags_new directly to a Number could lose precision.

For applications that need to handle large values, JavaScript's BigInt provides an appropriate integer representation.

For example:

const flagsNew = "2147483648";

const flags = BigInt(flagsNew);

const bit31 = 1n << 31n;

const isBit31Set = (flags & bit31) !== 0n;

console.log(isBit31Set);

This example checks whether bit 31 is set in the supplied value. It demonstrates the parsing approach; it does not imply that bit 31 corresponds to a particular application capability.

Remember that JavaScript BigInt cannot be mixed directly with ordinary numeric values in arithmetic or bitwise operations. Use compatible BigInt values throughout those calculations.

Developers working in other languages should similarly choose integer types or libraries that preserve the full value.

📈 Why This Matters for Discord's Developer Ecosystem

The addition of flags_new is a small change with a practical purpose.

Discord's developer platform supports bots, integrations, and other applications that depend on structured API responses. As the platform evolves, the representation of application metadata needs to accommodate new capabilities without unnecessarily breaking older consumers.

This update establishes a clear path:

Existing Numeric Flags → Expanded String Representation → Support for Higher Flag Bits

It also gives library maintainers a reason to review their Application object definitions, serialization logic, and flag parsing utilities.

Current versions of developer libraries may already expose flags_new, but developers should check the documentation for the specific library and version they use rather than assuming every integration has updated.

The change does not mean every bot needs an immediate rewrite. It means the API now has a defined way to represent application flags that exceed the legacy field's limits.

🚀 What Developers Should Do Next

For most developers, the sensible response is to understand the new field and update only where necessary.

Review how your application reads Discord's Application object. Check whether your code assumes that flags contains every possible flag. If your application needs to process future higher bit positions, make sure it uses flags_new and an appropriate integer representation.

If you maintain an SDK or API wrapper, verify that the Application object schema includes the new field as a string and that your implementation preserves its value.

Finally, remember that the new field is not a replacement for the request parameter. Discord's documentation explicitly says requests accepting flag values should continue to use flags.

The takeaway is simple: flags_new expands what Discord can represent without breaking the existing contract for legacy consumers.

That is the real significance of this API pivot. It creates room for new application flag bits while allowing existing integrations to continue working as expected.

🔗 Official Sources

1. Discord Application Resource Documentation

   The primary source for the flags and flags_new field types, bit limit, and request compatibility rules.

2. Discord API Documentation Repository

   The official repository for Discord's developer API documentation and schema updates.

3. Application Object API Reference in discord.js

5. Discord API Types Application Interface

   Useful for developers checking how the Application object is represented in TypeScript API definitions.

6. Discord API Permissions and Bitwise Operations

   Provides additional background on Discord's use of bit fields and integer serialization.