This describes the resources that make up the official GitHub API v3. If you have any problems or requests please contact
Current Version
By default, all requests receive the v3
of the API.
We encourage you to .
Accept: application/vnd.github.v3+json
All API access is over HTTPS, and accessed from the
domain (or through </api/v3/ for enterprise).
All data is
sent and received as JSON.
$ curl -i /users/octocat/orgs
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 Oct :14 GMT
Content-Type: application/ charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a0df2cb612"
X-GitHub-Media-Type: github.v3
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset:
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff
Blank fields are included as null instead of being omitted.
All timestamps are returned in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
Summary Representations
When you fetch a list of resources, the response includes a subset of the
attributes for that resource. This is the “summary” representation of the
resource. (Some attributes are computationally expensive for the API to provide.
For performance reasons, the summary representation excludes those attributes.
To obtain those attributes, fetch the “detailed” representation.)
Example: When you get a list of repositories, you get the summary
representation of each repository. Here, we fetch the list of repositories owned
organization:
GET /orgs/octokit/repos
Detailed Representations
When you fetch an individual resource, the response typically includes all
attributes for that resource. This is the “detailed” representation of the
resource. (Note that authorization sometimes influences the amount of detail
included in the representation.)
Example: When you get an individual repository, you get the detailed
representation of the repository. Here, we fetch the
repository:
GET /repos/octokit/octokit.rb
The documentation provides an example response for each API method. The example
response illustrates all attributes that are returned by that method.
Parameters
Many API methods take optional parameters. For GET requests, any parameters not
specified as a segment in the path can be passed as an HTTP query string
parameter:
$ curl -i "/repos/vmg/redcarpet/issues?state=closed"
In this example, the ‘vmg’ and ‘redcarpet’ values are provided for the :owner
and :repo parameters in the path while :state is passed in the query
For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON
with a Content-Type of ‘application/json’:
$ curl -i -u username -d '{"scopes":["public_repo"]}' /authorizations
Root Endpoint
You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports:
Note that for GitHub Enterprise, , you’ll need to pass in your GitHub Enterprise endpoint as the hostname, as well as your username and password:
$ curl https://hostname/api/v3/ -u username:password
Client Errors
There are three possible types of client errors on API calls that
receive request bodies:
Sending invalid JSON will result in a 400 Bad Request response.
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JSON"}
Sending the wrong type of JSON values will result in a 400 Bad
Request response.
HTTP/1.1 400 Bad Request
Content-Length: 40
{"message":"Body should be a JSON object"}
Sending invalid fields will result in a 422 Unprocessable Entity
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
"message": "Validation Failed",
"errors": [
"resource": "Issue",
"field": "title",
"code": "missing_field"
All error objects have resource and field properties so that your client
can tell what the problem is.
There’s also an error code to let you
know what is wrong with the field.
These are the possible validation error
Error Name
Description
This means a resource does not exist.
missing_field
This means a required field on a resource has not been set.
This means the formatting of a field is invalid.
The documentation for that resource should be able to give you more specific information.
already_exists
This means another resource has the same value as this field.
This can happen in resources that must have some unique key (such as Label names).
Resources may also send custom validation errors (where code is custom). Custom errors will always have a message field describing the error, as well as a documentation_url field pointing to some content that might help you resolve the error.
HTTP Redirects
API v3 uses HTTP redirection where appropriate. Clients should assume that any
request may result in a redirection. Receiving an HTTP redirection is not an
error and clients should follow that redirect. Redirect responses will have a
Location header field which contains the URI of the resource to which the
client should repeat the requests.
Status Code
Description
Permanent redirection. The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.
Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.
Other redirection status codes may be used in accordance with the HTTP 1.1 spec.
HTTP Verbs
Where possible, API v3 strives to use appropriate HTTP verbs for each
Description
Can be issued against any resource to get just the HTTP header info.
Used for retrieving resources.
Used for creating resources.
Used for updating resources with partial JSON data.
For instance, an Issue resource has title and body attributes.
A PATCH request may accept one or more of the attributes to update the resource.
PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
Used for deleting resources.
Authentication
There are three ways to authenticate through GitHub API v3.
Requests that
require authentication will return 404 Not Found, instead of
403 Forbidden, in some places.
This is to prevent the accidental leakage
of private repositories to unauthorized users.
Basic Authentication
$ curl -u "username"
$ curl -H "Authorization: token OAUTH-TOKEN"
OAuth2 Token (sent as a parameter)
$ curl /?access_token=OAUTH-TOKEN
Note that OAuth2 tokens can be , for applications that
are not websites.
OAuth2 Key/Secret
$ curl '/users/whatever?client_id=xxxx&client_secret=yyyy'
This should only be used in server to server scenarios.
Don’t leak your
OAuth application’s client secret to your users.
Failed login limit
Authenticating with invalid credentials will return 401 Unauthorized:
-u foo:bar
HTTP/1.1 401 Unauthorized
"message": "Bad credentials",
"documentation_url": "/v3"
After detecting several requests with invalid credentials within a short period,
the API will temporarily reject all authentication attempts for that user
(including ones with valid credentials) with 403 Forbidden:
-u valid_username:valid_password
HTTP/1.1 403 Forbidden
"message": "Maximum number of login attempts exceeded. Please try again later.",
"documentation_url": "/v3"
Hypermedia
All resources may have one or more *_url properties linking to other
resources.
These are meant to provide explicit URLs so that proper API clients
don’t need to construct URLs on their own.
It is highly recommended that API
clients use these.
Doing so will make future upgrades of the API easier for
developers.
All URLs are expected to be proper
URI templates.
You can then expand these templates using something like the
&& tmpl = URITemplate.new('/notifications{?since,all,participating}')
&& tmpl.expand
=& "/notifications"
&& tmpl.expand :all =& 1
=& "/notifications?all=1"
&& tmpl.expand :all =& 1, :participating =& 1
=& "/notifications?all=1&participating=1"
Pagination
Requests that return multiple items will be paginated to 30 items by
You can specify further pages with the ?page parameter. For some
resources, you can also set a custom page size up to 100 with the ?per_page parameter.
Note that for technical reasons not all endpoints respect the ?per_page parameter,
for example.
$ curl '/user/repos?page=2&per_page=100'
Note that page numbering is 1-based and that omitting the ?page
parameter will return the first page.
For more information on pagination, check out our guide on .
The pagination info is included in . It is important to
follow these Link header values instead of constructing your own URLs. In some
instances, such as in the , pagination is based on
SHA1 and not on page number.
Link: &/user/repos?page=3&per_page=100&; rel="next",
&/user/repos?page=50&per_page=100&; rel="last"
Linebreak is included for readability.
The possible rel values are:
Description
Shows the URL of the immediate next page of results.
Shows the URL of the last page of results.
Shows the URL of the first page of results.
Shows the URL of the immediate previous page of results.
Rate Limiting
For requests using Basic Authentication or OAuth, you can make up to 5,000
requests per hour. For unauthenticated requests, the rate limit allows you to
make up to 60 requests per hour. Unauthenticated requests are associated with your IP address,
and not the user making requests. Note that .
You can check the returned HTTP headers of any API request to see your current
rate limit status:
$ curl -i /users/whatever
HTTP/1.1 200 OK
Date: Mon, 01 Jul :06 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset:
The headers tell you everything you need to know about your current rate limit status:
Header Name
Description
X-RateLimit-Limit
The maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-Remaining
The number of requests remaining in the current rate limit window.
X-RateLimit-Reset
The time at which the current rate limit window resets in .
If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.
new Date( * 1000)
// =& Mon Jul 01 :53 GMT-0400 (EDT)
Once you go over the rate limit you will receive an error response:
HTTP/1.1 403 Forbidden
Date: Tue, 20 Aug :41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset:
"message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
"documentation_url": "/v3/#rate-limiting"
You can also
without incurring an
Increasing the unauthenticated rate limit for OAuth applications
If your OAuth application needs to make unauthenticated calls with a higher rate limit, you can pass your app’s client ID and secret as part of the query string.
$ curl -i '/users/whatever?client_id=xxxx&client_secret=yyyy'
HTTP/1.1 200 OK
Date: Mon, 01 Jul :06 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4966
X-RateLimit-Reset:
This method should only be used for server-to-server calls. You should never
share your client secret with anyone or include it in client-side browser code.
Staying within the rate limit
If you are using Basic Authentication or OAuth, and you are exceeding
your rate limit, you can likely fix the issue by caching API responses
and using .
If you’re using conditional requests and still exceeding your rate
limit, please
to request a
higher rate limit for your OAuth application.
Abuse Rate Limits
To prevent abuse, additional rate limits apply to some endpoints that
create content. This rate limit applies to the creation of new content
over a period of time. These rate limits do not apply to private repositories
or GitHub Enterprise installations.
It is not intended for this rate limit to interfere with any legitimate use of
the API. Your normal
should be the only
limit you target. Please
if your use is affected by
this rate limit.
If your application triggers this rate limit, you’ll receive an informative
HTTP/1.1 403 Forbidden
Content-Type: application/ charset=utf-8
Connection: close
"message": "You have triggered an abuse detection mechanism and have been temporarily blocked from content creation. Please retry your request again later.",
"documentation_url": "/v3#abuse-rate-limits"
User Agent Required
All API requests MUST include a valid User-Agent header. Requests with no User-Agent
header will be rejected. We request that you use your GitHub username, or the name of your
application, for the User-Agent header value. This allows us to contact you if there are problems.
Here’s an example:
User-Agent: Awesome-Octocat-App
If you provide an invalid User-Agent header, you will receive a 403 Forbidden response:
$ curl -iH 'User-Agent: ' /meta
HTTP/1.0 403 Forbidden
Connection: close
Content-Type: text/html
Request forbidden by administrative rules.
Please make sure your request has a User-Agent header.
for other possible causes.
Conditional requests
Most responses return an ETag header. Many responses also return a Last-Modified header. You can use the values
of these headers to make subsequent requests to those resources using the
If-None-Match and If-Modified-Since headers, respectively. If the resource
has not changed, the server will return a 304 Not Modified. Also note: making
a conditional request and receiving a 304 response does not count against your
, so we encourage you to use it whenever possible.
$ curl -i /user
HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "644b5bcc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul :30 GMT
Status: 200 OK
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996
X-RateLimit-Reset:
$ curl -i /user -H 'If-None-Match: "644b5bcc4bd9d8b1ae730"'
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
ETag: "644b5bcc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul :30 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996
X-RateLimit-Reset:
$ curl -i /user -H "If-Modified-Since: Thu, 05 Jul :30 GMT"
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
Last-Modified: Thu, 05 Jul :30 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996
X-RateLimit-Reset:
Cross Origin Resource Sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from
any origin.
You can read the , or
HTML 5 Security Guide.
Here’s a sample request sent from a browser hitting
-H "Origin: "
HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Allow-Credentials: true
This is what the CORS preflight request looks like:
-H "Origin: " -X OPTIONS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true
JSON-P Callbacks
You can send a ?callback parameter to any GET call to have the results
wrapped in a JSON function.
This is typically used when browsers want
to embed GitHub content in web pages by getting around cross domain
The response includes the same data output as the regular API,
plus the relevant HTTP Header information.
$ curl ?callback=foo
"status": 200,
"X-RateLimit-Limit": "5000",
"X-RateLimit-Remaining": "4966",
"X-RateLimit-Reset": "",
"Link": [ // pagination headers and other links
["?page=2", {"rel": "next"}]
// the data
You can write a JavaScript handler to process the callback. Here’s a minimal example you can try out:
&script type="text/javascript"&
function foo(response) {
var meta = response.
var data = response.
console.log(meta);
console.log(data);
var script = document.createElement('script');
script.src = '?callback=foo';
document.getElementsByTagName('head')[0].appendChild(script);
&p&Open up your browser's console.&/p&
All of the headers are the same String value as the HTTP Headers with one
notable exception: Link.
Link headers are pre-parsed for you and come
through as an array of [url, options] tuples.
A link that looks like this:
Link: &url1&; rel="next", &url2&; rel="foo"; bar="baz"
… will look like this in the Callback output:
"rel": "next"
"rel": "foo",
"bar": "baz"
Some requests allow for specifying timestamps or generate timestamps with time
zone information. We apply the following rules, in order of priority, to
determine timezone information for API calls.
For API calls that allow for a timestamp to be specified, we use that exact
timestamp. An example of this is the .
These timestamps look something like T15:05:06+01:00. Also see
how these timestamps can be specified.
It is possible to supply a Time-Zone header which defines a timezone according
$ curl -H "Time-Zone: Europe/Amsterdam" -X POST /repos/github/linguist/contents/new_file.md
This means that we generate a timestamp for the moment your API call is made in
the timezone this header defines. For example, the
generates a git commit for each addition or change and uses the current time
as the timestamp. This header will determine the timezone used for generating
that current timestamp.
If no Time-Zone header is specified and you make an authenticated call to the
API, we use the last known timezone for the authenticated user. The last known
timezone is updated whenever you browse
If the steps above don’t result in any information, we use UTC as the timezone
to create the git commit.
GitHub, Inc.MySQL 5.1 Reference Manual :: 6.3.2 Adding User Accounts
MySQL 5.1 Manual
Section Navigation &&&&&[]
6.3.2 Adding User Accounts
You can create MySQL accounts two ways:
By using account-management statements intended for creating
accounts and establishing their privileges, such as
. These statements cause
the server to make appropriate modifications to the underlying
grant tables.
By manipulating the MySQL grant tables directly with
statements such as ,
The preferred method is to use account-management statements
because they are more concise and less error-prone than
manipulating the grant tables directly. All such statements are
described in . Direct
grant table manipulation is discouraged, and is not described
here. The server is free to ignore rows that become malformed as a
result of such modifications.
Another option for creating accounts is to use the GUI tool
MySQL Workbench. Also, several third-party programs offer capabilities
for MySQL account administration. phpMyAdmin is
one such program.
The following examples show how to use the
client program to set up new accounts.
These examples assume that privileges have been set up according
to the defaults described in .
This means that to make changes, you must connect to the MySQL
server as the MySQL root user, which has the
privilege.
First, use the
program to connect to the
server as the MySQL root user:
shell& mysql --user=root mysql
If you have assigned a password to the root
account, you must also supply a --password or
-p option.
After connecting to the server as root, you can
add new accounts. The following example uses
statements to set up four
mysql& CREATE USER 'monty'@'localhost' IDENTIFIED BY 'some_pass';
mysql& GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'
WITH GRANT OPTION;
mysql& CREATE USER 'monty'@'%' IDENTIFIED BY 'some_pass';
mysql& GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'
WITH GRANT OPTION;
mysql& CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass';
mysql& GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
mysql& CREATE USER 'dummy'@'localhost';
The accounts created by those statements have the following
properties:
Two accounts have a user name of monty and
a password of some_pass. Both are superuser
accounts with full privileges to do anything. The
'monty'@'localhost' account can be used
only when connecting from the local host. The
'monty'@'%' account uses the
'%' wildcard for the host part, so it can
be used to connect from any host.
The 'monty'@'localhost' account is
necessary if there is an anonymous-user account for
localhost. Without the
'monty'@'localhost' account, that
anonymous-user account takes precedence when
monty connects from the local host and
monty is treated as an anonymous user. The
reason for this is that the anonymous-user account has a more
specific Host column value than the
'monty'@'%' account and thus comes earlier
in the user table sort order.
(user table sorting is discussed in
The 'admin'@'localhost' account has a
password of admin_pass. This account can be
used only by admin to connect from the
local host. It is granted the
administrative
privileges. These privileges enable the
admin user to execute the
commands, as
privileges are granted for accessing any databases. You could
add such privileges using
statements.
The 'dummy'@'localhost' account has no
password (which is insecure and not recommended). This account
can be used only to connect from the local host. No privileges
are granted. It is assumed that you will grant specific
privileges to the account using
statements.
To see the privileges for an account, use
mysql& SHOW GRANTS FOR 'admin'@'localhost';
+-----------------------------------------------------+
| Grants for admin@localhost
+-----------------------------------------------------+
| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' |
+-----------------------------------------------------+
The next examples create three accounts and grant them access to
specific databases. Each of them has a user name of
custom and password of
mysql& CREATE USER 'custom'@'localhost' IDENTIFIED BY 'obscure';
mysql& GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON bankaccount.*
TO 'custom'@'localhost';
mysql& CREATE USER 'custom'@'' IDENTIFIED BY 'obscure';
mysql& GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON expenses.*
TO 'custom'@'';
mysql& CREATE USER 'custom'@'%.' IDENTIFIED BY 'obscure';
mysql& GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON customer.*
TO 'custom'@'%.';
The three accounts can be used as follows:
The first account can access the
bankaccount database, but only from the
local host.
The second account can access the expenses
database, but only from the host
The third account can access the customer
database, from any host in the
domain. This account has access from all machines in the
domain due to use of the “%”
wildcard character in the host part of the account name.