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 unchangeable. 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. Pull Request attribute: merge_commit_sha

    Recommendation: Do not use this attribute.

11. Rate Limit attribute: rate

    Recommendation: Use resources[“core”] instead.

12. Repository attribute: forks

    Recommendation: Use forks_count instead.

13. Repository attribute: master_branch

    Recommendation: Use default_branch instead.

14. Repository attribute: open_issues

    Recommendation: Use open_issues_count instead.

15. 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.

16. Repository attribute: watchers

    Recommendation: Use watchers_count instead.

17. User attribute: bio

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

18. User attribute: plan[“collaborators”]

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

19. User attribute: gravatar_id

    Recommendation: Use avatar_url instead.

20. Feed attribute: current_user_organization_url

    Recommendation: Use current_user_organization_urls instead.

21. Feed attribute: current_user_organization

    Recommendation: Use current_user_organizations instead.

22. 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.

23. 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.

beta (Deprecated)

The beta API is deprecated. Its current functionality is stable and unchangeable. Please file a support issue if you have problems.

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.