Organizations API

The organizations API endpoint:

  • Allows you to list organizations and retrieve information about a Buildkite organization.

  • Forms the basis of several more Buildkite REST API endpoints, such as those for pipelines and teams.

Inactive organizations are omitted

The API returns only organizations with an active plan, including the Free plan. If an evaluation trial has ended and no plan is selected, the API omits that organization. Requests for it return 404 with {"message":"No organization found"}. Choose a plan on the organization's billing page to make the organization available to the API again.

List organizations

Returns a paginated list of organizations accessible by the user's access token.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations"

[
  {
    "id": "bb3125de-4dc9-44cf-ad18-65d2b71a5a34",
    "graphql_id": "T3JnYW5pemF0aW9uLS0tOGEzMjAwOTMtMjE4OC00MmNiLWI5ZGQtNzE4NjZjZTYyYjA4",
    "url": "https://api.buildkite.com/v2/organizations/my-great-org",
    "web_url": "https://buildkite.com/my-great-org",
    "name": "My Great Org",
    "slug": "my-great-org",
    "pipelines_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines",
    "agents_url": "https://api.buildkite.com/v2/organizations/my-great-org/agents",
    "emojis_url": "https://api.buildkite.com/v2/organizations/my-great-org/emojis",
    "created_at": "2015-05-09T21:05:59.874Z"
  }
]

Required scope: read_organizations

Success response: 200 OK

Get an organization

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}"

{
  "id": "bb3125de-4dc9-44cf-ad18-65d2b71a5a34",
  "graphql_id": "T3JnYW5pemF0aW9uLS0tOGEzMjAwOTMtMjE4OC00MmNiLWI5ZGQtNzE4NjZjZTYyYjA4",
  "url": "https://api.buildkite.com/v2/organizations/my-great-org",
  "web_url": "https://buildkite.com/my-great-org",
  "name": "My Great Org",
  "slug": "my-great-org",
  "pipelines_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines",
  "agents_url": "https://api.buildkite.com/v2/organizations/my-great-org/agents",
  "emojis_url": "https://api.buildkite.com/v2/organizations/my-great-org/emojis",
  "created_at": "2015-05-09T21:05:59.874Z"
}

Required scope: read_organizations

Success response: 200 OK