Decoding GitHub’s Media Types: `application/vnd.github+json` vs `application/vnd.github.v3+json`

Author’s note:

Question: How does vnd.github.v3+json differ from vnd.github+json?

Context: Context:

I don’t notice that my github actions need the v3.

Executive Summary

For developers navigating GitHub’s API documentation or maintaining legacy integrations, the distinction between application/vnd.github+json and application/vnd.github.v3+json often causes confusion.

The short answer is that application/vnd.github+json is the modern, recommended standard for virtually all GitHub REST API interactions ¹. The version-specific application/vnd.github.v3+json was historically used to explicitly request the “v3” API surface, particularly to distinguish it from beta “preview” media types ².

Today, GitHub has shifted to a calendar-based versioning system. Instead of relying on the media type to define the API version, you should now use the generic media type (application/vnd.github+json) combined with a specific version header (X-GitHub-Api-Version) ³. If your GitHub Actions are working without the v3 specifier, it is because the API automatically defaults to a stable version (currently 2022-11-28) when no version is explicitly requested ³.

Anatomy of a GitHub Media Type

To understand the difference, it helps to break down the syntax of these media types, which follow the RFC 6838 standard for vendor-specific trees ⁴.

application/: The top-level type.
vnd.: Indicates a “vendor” specific tree (in this case, GitHub) ⁵.
github: The vendor identifier.
.v3 (Optional): A parameter explicitly requesting version 3 of the API resources.
+json: The suffix indicating the underlying format is JSON.

The vnd.github tree is flexible. It allows GitHub to define not just versioning, but also format variations like .raw (for raw file content), .html (for rendered markdown), or .diff (for commit differences) ⁶.

Historical Evolution: From `v3` to Calendar Versioning

The Era of Explicit `v3`

In the past, GitHub used the media type to manage API stability. When new features were introduced (like the Licenses API or Git Signing API), they were often released under “preview” media types (e.g., application/vnd.github.cryptographer-preview) ².

To exit these preview modes and use the stable API, developers were instructed to switch their Accept header to application/vnd.github.v3+json ². This explicitly told the server: “I want the stable v3 representation, not the beta preview.”

The Modern Era (2022–Present)

On November 28, 2022, GitHub introduced calendar-based versioning to ensure long-term stability without breaking changes ⁷.

Under this new system:

Media Type: The generic application/vnd.github+json is recommended for almost all endpoints ¹.
Versioning: The version is controlled by the X-GitHub-Api-Version header (e.g., 2022-11-28) ³.

This decoupling means you no longer need to embed the version (v3) inside the media type string.

Current Official Guidance

If you are building a new integration or updating an old one in 2026, follow these rules:

1. Use the Generic Media Type

Most REST API endpoints specify that you should pass an Accept header with the value application/vnd.github+json ¹. This ensures you receive the standard JSON response.

2. Use the Version Header

To protect your application from future breaking changes, you should include the X-GitHub-Api-Version header. If you omit this header, GitHub will default to the 2022-11-28 version ³.

3. Why Your Actions Work Without `v3`

You noted that your GitHub Actions function correctly without specifying v3. This is expected behavior. Because requests without the X-GitHub-Api-Version header default to the 2022-11-28 version ³, your Actions are automatically served a stable API response. However, relying on this implicit default is risky for long-term maintenance, as the default version could theoretically change in the future ⁸.

Comparison: Media Types at a Glance

Media Type	Primary Use Case	Status
`application/vnd.github+json`	The standard `Accept` header for all REST API requests.	Recommended ¹
`application/vnd.github.v3+json`	Legacy method to pin requests to API v3.	Supported but superseded by headers ²
`application/vnd.github.raw+json`	Requesting raw file contents (e.g., downloading a file).	Active / Specialized ⁶
`application/vnd.github.html+json`	Requesting HTML-rendered content (e.g., READMEs).	Active / Specialized ⁶
`application/vnd.github.object+json`	Ensuring consistent object responses for directory contents.	Active / Specialized ⁶
*`-preview` types**	Accessing beta features (e.g., `cryptographer-preview`).	Deprecated (Many return 400 errors) ²

Practical Examples

Legacy Request (Explicit `v3`)

This style was common before 2022 but is now less favored.

curl -L \
 -H "Accept: application/vnd.github.v3+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 https://api.github.com/user

Modern Best Practice Request

This is the recommended approach for 2026.

curl -L \
 -H "Accept: application/vnd.github+json" \
 -H "X-GitHub-Api-Version: 2022-11-28" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 https://api.github.com/user

Requesting a Custom Format (Raw)

Use the vendor tree to request specific formats, like raw file content.

curl -L \
 -H "Accept: application/vnd.github.raw+json" \
 -H "X-GitHub-Api-Version: 2022-11-28" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 https://api.github.com/repos/octocat/Hello-World/contents/README.md

Common Pitfalls

1. The “Preview” Trap

Do not use old preview media types found in outdated Stack Overflow answers (e.g., application/vnd.github.mercy-preview). GitHub has removed many of these, and using them can result in 400 Bad Request errors ².

2. Content-Type vs. Accept

Remember that these vendor-specific types are strictly for the Accept header (content negotiation). For the Content-Type header (sending data to GitHub), you should generally use standard application/json ⁹.

3. Implicit Defaults

While your code works now without a version header, GitHub warns that “the default version of the API may change in the future” ⁸. Relying on the implicit default leaves your integration vulnerable to breaking changes if GitHub updates the default version.

Bottom Line

vnd.github+json is the current standard. Use it for all general API requests.
vnd.github.v3+json is a legacy artifact. It works, but it’s no longer the primary way to handle versioning.
Action Item: Update your integrations to use Accept: application/vnd.github+json and explicitly set the X-GitHub-Api-Version: 2022-11-28 header. This guarantees your code will keep working even if GitHub releases a new API version in the future.