Annotations API

Annotation data model

An annotation is a snippet of Markdown uploaded by your agent during the execution of a build's job. Annotations are created using the buildkite-agent annotate command from within a job.

id ID of the annotation
context The "context" specified when annotating the build. Only one annotation per build may have any given context value.
style The style of the annotation. Can be `success`, `info`, `warning` or `error`.
body_html Rendered HTML of the annotation's body
created_at When the annotation was first created
updated_at When the annotation was last added to or replaced

List annotations for a build

Returns a paginated list of a build's annotations.

Note that you need the build number to retrieve annotations, not the build ID.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/annotations"
[
  {
    "id": "de0d4ab5-6360-467a-a34b-e5ef5db5320d",
    "context": "default",
    "style": "info",
    "body_html": "<h1>My Markdown Heading</h1>\n<img src=\"artifact://indy.png\" alt=\"Belongs in a museum\" height=250 />",
    "created_at": "2019-04-09T18:07:15.775Z",
    "updated_at": "2019-08-06T20:58:49.396Z"
  },
  {
    "id": "5b3ceff6-78cb-4fe9-88ae-51be5f145977",
    "context": "coverage",
    "style": "info",
    "body_html": "Read the <a href=\"artifact://coverage/index.html\">uploaded coverage report</a>",
    "created_at": "2019-04-09T18:07:16.320Z",
    "updated_at": "2019-04-09T18:07:16.320Z"
  }
]

Required scope: read_builds

Success response: 200 OK

Create an annotation on a build

Creates an annotation on a build.

Note that you need the build number to create annotations, not the build ID.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/annotations" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hello world!",
    "style": "info",
    "priority": 5,
    "context": "greeting"
  }'
{
  "id": "018b8d10-6b5b-4df2-b0ff-dfa2af566050",
  "context": "greeting",
  "style": "info",
  "priority": 5,
  "body_html": "<p>Hello world!</p>\n",
  "created_at": "2023-11-01T22:45:45.435Z",
  "updated_at": "2023-11-01T22:45:45.435Z"
}

Required request body properties:

body The annotation's body, as HTML or Markdown.

Example: "My annotation here"

Optional request body properties:

style The style of the annotation. Can be success, info, warning or error.

Example: "info"

priority The priority of the annotation (`1` to `10`). Annotations with a priority of `10` are shown first, while annotations with a priority of `1` are shown last. When this option is not specified, annotations have a default priority of `3`.

Example: 5

context A string value by which to identify the annotation on the build. This is useful when appending to an existing annotation. Only one annotation per build may have any given context value.

Example: "coverage"

append Whether to append the given body onto the annotation with the same context.

Example: true

Required scope: write_builds

Success response: 201 Created

Delete an annotation on a build

Deletes an annotation on a build.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/annotations/{annotation.uuid}"