Organization banner API

The organization banner API lets you manage the system banner shown at the top of every page for members of a Buildkite organization. An organization has at most one active banner, so PUT creates the banner if none exists, or updates the existing one.

Enterprise plan feature

The system banners feature is only available to Buildkite customers on Enterprise plans.

These endpoints require a read_organization_settings or write_organization_settings access token scope, and the authenticated user must be a Buildkite organization administrator on a plan that includes system banners.

Get the banner

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

{
  "uuid": "01a0fe3d-3faa-7ada-9168-23bc3e4f4788",
  "graphql_id": "T3JnYW5pemF0aW9uQmFubmVyLS0tMDFhMGZlM2QtM2ZhYS03YWRhLTkxNjgtMjNiYzNlNGY0Nzg4",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/banner",
  "message": "Deploy freeze until Monday",
  "created_at": "2026-10-02T20:10:21.992Z",
  "updated_at": "2026-10-02T20:10:21.992Z"
}

Required scope: read_organization_settings

Success response: 200 OK

Error responses:

403 Forbidden The token does not have the read_organization_settings scope, the authenticated user is not an organization administrator, or the organization's plan does not include system banners.
404 Not Found The organization has no active banner.

Create or update the banner

Creates the banner if the organization doesn't have one, or updates the existing banner's message. The response status indicates which happened.

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/banner" \
  -d '{
    "message": "Deploy freeze until Monday"
  }'

{
  "uuid": "01a0fe3d-3faa-7ada-9168-23bc3e4f4788",
  "graphql_id": "T3JnYW5pemF0aW9uQmFubmVyLS0tMDFhMGZlM2QtM2ZhYS03YWRhLTkxNjgtMjNiYzNlNGY0Nzg4",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/banner",
  "message": "Deploy freeze until Monday",
  "created_at": "2026-10-02T20:10:21.992Z",
  "updated_at": "2026-10-02T20:10:21.992Z"
}

Request fields:

message Required. The banner message to display to organization members. Must be a string of no more than 2,000 characters.

Required scope: write_organization_settings

Success response: 201 Created when a banner is created, 200 OK when an existing banner is updated.

Error responses:

403 Forbidden The token does not have the write_organization_settings scope, the authenticated user is not an organization administrator, or the organization's plan does not include system banners.
422 Unprocessable Entity message is missing, isn't a string, is blank, or is longer than 2,000 characters.

Delete the banner

Removes the organization's active banner.

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

Required scope: write_organization_settings

Success response: 204 No Content

Error responses:

403 Forbidden The token does not have the write_organization_settings scope, the authenticated user is not an organization administrator, or the organization's plan does not include system banners.
404 Not Found The organization has no active banner.