Organizations

List your organizations

List organizations for the authenticated user.

OAuth scope requirements

Currently, OAuth requests always receive the user’s public organization memberships, regardless of the OAuth scopes associated with the request. If the OAuth authorization has user or read:org scope, the response also includes private organization memberships.

With the new Organization Permissions API (described below), this method will only return organizations that your authorization allows you to operate on in some way (e.g., you can list teams with read:org scope, you can publicize your organization membership with user scope, etc.). Therefore, this API will require at least user or read:org scope. OAuth requests with insufficient scope will receive a 403 Forbidden response.

We're currently offering a migration period allowing applications to opt in to the Organization Permissions API. This functionality will soon apply to all API consumers. Please see the blog post for full details.

To access the API during the migration period, you must provide a custom media type in the Accept header:

application/vnd.github.moondragon+json
GET /user/orgs

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "login": "github",
    "id": 1,
    "url": "https://api.github.com/orgs/github",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
]

List user organizations

List public organization memberships for the specified user.

Currently, if you make an authenticated call, you can also list your private memberships in organizations (but only for the currently authenticated user).

With the new Organization Permissions API (described below), this method will only list public memberships, regardless of authentication. If you need to fetch all of the organization memberships (public and private) for the authenticated user, use the List your organizations API instead.

We're currently offering a migration period allowing applications to opt in to the Organization Permissions API. This functionality will soon apply to all API consumers. Please see the blog post for full details.

To access the API during the migration period, you must provide a custom media type in the Accept header:

application/vnd.github.moondragon+json
GET /users/:username/orgs

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "login": "github",
    "id": 1,
    "url": "https://api.github.com/orgs/github",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
]

Get an organization

GET /orgs/:org

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "login": "github",
  "id": 1,
  "url": "https://api.github.com/orgs/github",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization",
  "name": "github",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "html_url": "https://github.com/octocat",
  "created_at": "2008-01-14T04:33:35Z",
  "type": "Organization"
}

Edit an organization

PATCH /orgs/:org

Input

Name Type Description
billing_email string Billing email address. This address is not publicized.
company string The company name.
email string The publicly visible email address.
location string The location.
name string The shorthand name of the company.
description string The description of the company.

Example

{
  "billing_email": "support@github.com",
  "blog": "https://github.com/blog",
  "company": "GitHub",
  "email": "support@github.com",
  "location": "San Francisco",
  "name": "github",
  "description": "GitHub, the company."
}

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "login": "github",
  "id": 1,
  "url": "https://api.github.com/orgs/github",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization",
  "name": "github",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "html_url": "https://github.com/octocat",
  "created_at": "2008-01-14T04:33:35Z",
  "type": "Organization",
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "private_gists": 81,
  "disk_usage": 10000,
  "collaborators": 8,
  "billing_email": "support@github.com",
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20
  }
}