Add support for creating Insights annotations (POST /v2/insights-annotation/create/)

Author: Jonathan Visser

src/Service/InsightsAnnotation.php

@@ -10,6 +10,7 @@
 class InsightsAnnotation extends AbstractService
 {
     public const V2_INSIGHTS_ANNOTATION_LIST_URL = "/v2/insights-annotation/";
+    public const V2_INSIGHTS_ANNOTATION_CREATE_URL = "/v2/insights-annotation/create/";
 
     /**
      * List all custom Insights annotations for the Hypernodes you have access
@@ -45,4 +46,30 @@ public function getList(array $params = []): array
 
         return $annotations;
     }
+
+    /**
+     * Create a custom Insights annotation for a Hypernode. The annotation is
+     * shown in the Insights graphs at the point in time given by `x_axis` (a
+     * unix timestamp in seconds). Optionally restrict the annotation to
+     * specific graphs with `metrics`, a comma-separated list of metric names;
+     * when omitted, the annotation applies to all metrics.
+     *
+     * @param array $data Annotation data, requires at least the keys
+     *  `name`, `x_axis` and `app`.
+     * @return array The created annotation
+     * @throws HypernodeApiClientException
+     * @throws HypernodeApiServerException
+     */
+    public function create(array $data): array
+    {
+        $response = $this->client->api->post(
+            self::V2_INSIGHTS_ANNOTATION_CREATE_URL,
+            [],
+            json_encode($data)
+        );
+
+        $this->client->maybeThrowApiExceptions($response);
+
+        return $this->client->getJsonFromResponse($response);
+    }
 }

tests/unit/Service/InsightsAnnotationTest.php

@@ -124,4 +124,55 @@ public function testGetListRaisesServerExceptions()
 
         $this->client->insightsAnnotation->getList();
     }
+
+    public function testCreate()
+    {
+        $annotationData = [
+            'name' => 'Deployed release 1.2.3',
+            'x_axis' => 1756384957,
+            'app' => 'johndoe',
+            'metrics' => 'memory_usage',
+        ];
+        $createdAnnotation = array_merge($annotationData, [
+            'id' => 123,
+            'created' => '2026-07-15T12:00:00Z',
+            'modified' => '2026-07-15T12:00:00Z',
+        ]);
+        $this->responses->append(
+            new Response(201, [], json_encode($createdAnnotation)),
+        );
+
+        $result = $this->client->insightsAnnotation->create($annotationData);
+
+        $request = $this->responses->getLastRequest();
+        $this->assertEquals('POST', $request->getMethod());
+        $this->assertEquals('/v2/insights-annotation/create/', $request->getUri());
+        $this->assertJson((string)$request->getBody());
+        $this->assertEquals($annotationData, json_decode((string)$request->getBody(), true));
+        $this->assertEquals($createdAnnotation, $result);
+    }
+
+    public function testCreateRaisesClientExceptions()
+    {
+        $badRequestResponse = new Response(400, [], json_encode([
+            'non_field_errors' => ['Your request was invalid.']
+        ]));
+        $this->responses->append($badRequestResponse);
+
+        $this->expectExceptionObject(new HypernodeApiClientException($badRequestResponse));
+
+        $this->client->insightsAnnotation->create(['name' => 'Deployed release 1.2.3']);
+    }
+
+    public function testCreateRaisesServerExceptions()
+    {
+        $badRequestResponse = new Response(500, [], json_encode([
+            'non_field_errors' => ['Something went wrong processing your request.']
+        ]));
+        $this->responses->append($badRequestResponse);
+
+        $this->expectExceptionObject(new HypernodeApiServerException($badRequestResponse));
+
+        $this->client->insightsAnnotation->create(['name' => 'Deployed release 1.2.3']);
+    }
 }