Versions

There are two stable versions of the GitHub API: the v3 version and the deprecated beta version. There are just a few differences between these two versions.

By default, all requests receive the v3 version. We encourage you to request a specific version via the Accept header.

v3

The v3 API is stable, and we strive to ensure that all changes are backwards compatible. Please file a support issue if you have problems.

Some v3 functionality is deprecated and will be removed in the next major version of the API.

Differences from beta version

The v3 media type differs from the beta media type in just a few places:

Gist JSON

For Gists, the v3 media type renames the user attribute to owner.

Issue JSON

When an issue is not a pull request, the v3 media type omits the pull_request attribute.

Repository JSON

For Repositories, the v3 media type omits the master_branch attribute. API clients should use the default_branch attribute to obtain the repository's default branch.

User Emails JSON

For User Emails, the v3 media type returns an array of objects (instead of an array of strings).

v3 deprecations

The following functionality is deprecated. For backwards compatibility purposes, v3 will continue to provide this functionality. However, this deprecated functionality will be removed in the next major version of the API.

The recommendations below will help you prepare your application for the next major version of the API.

  1. Method: /gists/:id/fork

    Recommendation: Use /gists/:id/forks (plural) instead.

  2. Method: /legacy/issues/search/:owner/:repository/:state/:keyword

    Recommendation: Use v3 Issue Search API instead.

  3. Method: /legacy/repos/search/:keyword

    Recommendation: Use v3 Repository Search API instead.

  4. Method: /legacy/user/search/:keyword

    Recommendation: Use v3 User Search API instead.

  5. Method: /legacy/user/email/:email

    Recommendation: Use v3 User Search API instead.

  6. Method: /repos/:owner/:repo/hooks/:id/test

    Recommendation: Use /repos/:owner/:repo/hooks/:id/tests (plural) instead.

  7. Method: /teams/:id/members/:username

    Recommendation: Use Get Team Membership, Add Team Membership, and Remove Team Membership instead.

  8. Query parameters when POSTing to /repos/:owner/:repo/forks

    Recommendation: Use JSON to POST to this method instead.

  9. Query parameter value: Passing "watchers" as the value for the "sort" parameter in a GET request to /repos/:owner/:repo/forks

    Recommendation: Use stargazers as the value instead.

  10. Rate Limit attribute: rate

    Recommendation: Use resources["core"] instead.

  11. Repository attribute: forks

    Recommendation: Use forks_count instead.

  12. Repository attribute: master_branch

    Recommendation: Use default_branch instead.

  13. Repository attribute: open_issues

    Recommendation: Use open_issues_count instead.

  14. Repository attribute: public

    Recommendation: When creating a repository, use the private attribute to indicate whether the repository should be public or private. Do not use the public attribute.

  15. Repository attribute: watchers

    Recommendation: Use watchers_count instead.

  16. User attribute: plan["collaborators"]

    Recommendation: Do not use this attribute. It is obsolete.

  17. User attribute: gravatar_id

    Recommendation: Use avatar_url instead.

  18. Feed attribute: current_user_organization_url

    Recommendation: Use current_user_organization_urls instead.

  19. Feed attribute: current_user_organization

    Recommendation: Use current_user_organizations instead.

  20. Pagination parameters top and sha for method: /repos/:owner/:repo/commits

    Recommendation: When fetching the list of commits for a repository use the standard per_page and page parameters for pagination, instead of per_page, top, and sha.

  21. Authorization attribute: token

    Recommendation: This attribute will return an empty string in the majority of the Authorizations API responses. Please see the deprecation blog post and the Authorizations API deprecation notice for full details.

  22. Team attribute: permission

    Recommendation: This attribute no longer dictates the permission a team has on its repositories; it only dictates the default permission that the Add or update team repository API will use for requests where no permission attribute is specified. To change the permission level for every repository on a team, use the List team repositories API to list all of the team's repositories, and then use the Add or update team repository with a permission attribute to update each repository's permission separately.

  23. Issue attribute: assignee

    Recommendation: Use the assignees key instead, since issues can have more than one assignee. Alternatively, you can use the assignees endpoints.

beta (Deprecated)

The beta API is deprecated. Its current functionality is stable, and we strive to ensure that any changes are backwards compatible. Please file a support issue if you have problems.

Note: We recommend using the v3 API instead of the deprecated beta version of the API.

The beta media type differs from the v3 media type in just a few places. In most cases, migrating an application from the beta media type to the v3 media type is smooth and painless.

We will eventually retire the beta version, but we have no official retirement date to announce at the moment. When the time comes, rest assured that we'll announce the retirement with plenty of notice.

Breaking beta changes

June 15th, 2011:

  • gravatar_url is being deprecated in favor of avatar_url for all responses that include users or orgs. A default size is no longer included in the URL.
  • Creating new gists (both anonymously and with an authenticated user) should use POST /gists from now on. POST /users/:username/gists is no longer supported.

June 1st, 2011:

  • Removed support for PUT verb on update requests. Use POST or PATCH instead.
  • Removed .json extension from all URLs.
  • No longer using the X-Next or X-Last headers. Pagination info is returned in the Link header instead.
  • JSON-P response has completely changed to a more consistent format.
  • Starring gists now uses PUT verb (instead of POST) and returns 204.

v2

We removed support for API v2 on June 12, 2012.

v1

We removed support for API v1 on June 12, 2012.