Add REST API docs for creating annotations (#2546)

Add REST API docs for creating annotations

While here, add missing attributes to jobs in builds:

- parallel_group_index
- parallel_group_total
- matrix
- cluster_id
- cluster_url
- cluster_queue_id
- cluster_queue_url

Just null for these for now (they're all optional), but we should look to expand on these in the future.

pages/apis/rest_api/annotations.md

@@ -51,3 +51,77 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.
 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 <a href="/docs/apis/rest-api/builds#build-number-vs-build-id">build number</a> to create annotations, not the build ID.
+
+```bash
+curl -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",
+    "context": "greeting"
+  }'
+```
+
+```json
+{
+  "id": "018b8d10-6b5b-4df2-b0ff-dfa2af566050",
+  "context": "greeting",
+  "style": "info",
+  "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](/docs/api#request-body-properties):
+
+<table class="responsive-table">
+<tbody>
+  <tr>
+    <th><code>body</code></th>
+    <td>
+      The annotation's body, as <a href="/docs/agent/v3/cli-annotate#supported-markdown-syntax">HTML or Markdown</a>.
+      <p class="Docs__api-param-eg"><em>Example:</em> <code>"My annotation here"</code></p>
+    </td>
+  </tr>
+</tbody>
+</table>
+
+Optional [request body properties](/docs/api#request-body-properties):
+
+<table class="responsive-table">
+<tbody>
+  <tr>
+    <th><code>style</code></th>
+    <td>
+      The style of the annotation. Can be <code>success</code>, <code>info</code>, <code>warning</code> or <code>error</code>.
+      <p class="Docs__api-param-eg"><em>Example:</em> <code>"info"</code></p>
+    </td>
+  </tr>
+  <tr>
+    <th><code>context</code></th>
+    <td>
+      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.
+      <p class="Docs__api-param-eg"><em>Example:</em> <code>"coverage"</code></p>
+    </td>
+  </tr>
+  <tr>
+    <th><code>append</code></th>
+    <td>
+      Whether to append the given <code>body</code> onto the annotation with the same context.
+      <p class="Docs__api-param-eg"><em>Example:</em> <code>true</code></p>
+    </td>
+  </tr>
+</tbody>
+</table>
+
+Required scope: `write_builds`
+
+Success response: `201 Created`

pages/apis/rest_api/builds.md

@@ -124,9 +124,16 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.
         "started_at": "2015-05-09T21:07:59.874Z",
         "finished_at": "2015-05-09T21:08:59.874Z",
         "retried": false,
-	"retried_in_job_id": null,
-	"retries_count": null,
-	"retry_type": null
+        "retried_in_job_id": null,
+        "retries_count": null,
+        "retry_type": null,
+        "parallel_group_index": null,
+        "parallel_group_total": null,
+        "matrix": null,
+        "cluster_id": null,
+        "cluster_url": null,
+        "cluster_queue_id": null,
+        "cluster_queue_url": null
       }
     ],
     "created_at": "2015-05-09T21:05:59.874Z",
@@ -276,7 +283,14 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.
       "retried": false,
       "retried_in_job_id": null,
       "retries_count": null,
-      "retry_type": null
+      "retry_type": null,
+      "parallel_group_index": null,
+      "parallel_group_total": null,
+      "matrix": null,
+      "cluster_id": null,
+      "cluster_url": null,
+      "cluster_queue_id": null,
+      "cluster_queue_url": null
     }
   ],
   "created_at": "2015-05-09T21:05:59.874Z",
@@ -439,7 +453,14 @@ curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{p
       "retried": false,
       "retried_in_job_id": null,
       "retries_count": null,
-      "retry_type": null
+      "retry_type": null,
+      "parallel_group_index": null,
+      "parallel_group_total": null,
+      "matrix": null,
+      "cluster_id": null,
+      "cluster_url": null,
+      "cluster_queue_id": null,
+      "cluster_queue_url": null
     }
   ],
   "created_at": "2015-05-09T21:05:59.874Z",
@@ -605,7 +626,14 @@ curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pi
       "retried": false,
       "retried_in_job_id": null,
       "retries_count": null,
-      "retry_type": null
+      "retry_type": null,
+      "parallel_group_index": null,
+      "parallel_group_total": null,
+      "matrix": null,
+      "cluster_id": null,
+      "cluster_url": null,
+      "cluster_queue_id": null,
+      "cluster_queue_url": null
     }
   ],
   "created_at": "2015-05-09T21:05:59.874Z",
@@ -745,7 +773,14 @@ curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pi
       "retried": false,
       "retried_in_job_id": null,
       "retries_count": null,
-      "retry_type": null
+      "retry_type": null,
+      "parallel_group_index": null,
+      "parallel_group_total": null,
+      "matrix": null,
+      "cluster_id": null,
+      "cluster_url": null,
+      "cluster_queue_id": null,
+      "cluster_queue_url": null
     }
   ],
   "created_at": "2015-05-09T21:05:59.874Z",

pages/apis/rest_api/pipelines.md

@@ -1035,7 +1035,7 @@ curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{s
 
 Required scope: `write_pipelines`
 
-Success response: `201 CREATED`
+Success response: `201 Created`
 
 Error responses: