Create annotation

curl --request POST \
  --url https://api.cloud.corbado.io/v1/observe/annotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "headline": "<string>",
  "description": "<string>",
  "dateFrom": "2026-09-17T09:45:00",
  "dateTo": "2026-09-21T18:00:00",
  "approximate": true,
  "reading": "<string>",
  "scope": {
    "applicationID": "<string>",
    "os": "<string>",
    "osVersion": "<string>",
    "browser": "<string>",
    "customTag1": "<string>",
    "customTag2": "<string>",
    "customTag3": "<string>",
    "customTag4": "<string>",
    "customTag5": "<string>",
    "customTag6": "<string>",
    "customTag7": "<string>",
    "customTag8": "<string>",
    "customTag9": "<string>",
    "customTag10": "<string>",
    "customTag11": "<string>",
    "customTag12": "<string>",
    "customTag13": "<string>",
    "customTag14": "<string>",
    "customTag15": "<string>",
    "customTag16": "<string>",
    "customTag17": "<string>",
    "customTag18": "<string>",
    "customTag19": "<string>",
    "customTag20": "<string>",
    "experimentRunID": "<string>",
    "experimentVariantID": "<string>"
  },
  "series": [
    "<string>"
  ],
  "display": true,
  "evidence": [],
  "refs": [
    {
      "value": "<string>"
    }
  ],
  "externalKey": "release-2026.10.1",
  "note": "<string>"
}
'

import requests

url = "https://api.cloud.corbado.io/v1/observe/annotations"

payload = {
    "headline": "<string>",
    "description": "<string>",
    "dateFrom": "2026-09-17T09:45:00",
    "dateTo": "2026-09-21T18:00:00",
    "approximate": True,
    "reading": "<string>",
    "scope": {
        "applicationID": "<string>",
        "os": "<string>",
        "osVersion": "<string>",
        "browser": "<string>",
        "customTag1": "<string>",
        "customTag2": "<string>",
        "customTag3": "<string>",
        "customTag4": "<string>",
        "customTag5": "<string>",
        "customTag6": "<string>",
        "customTag7": "<string>",
        "customTag8": "<string>",
        "customTag9": "<string>",
        "customTag10": "<string>",
        "customTag11": "<string>",
        "customTag12": "<string>",
        "customTag13": "<string>",
        "customTag14": "<string>",
        "customTag15": "<string>",
        "customTag16": "<string>",
        "customTag17": "<string>",
        "customTag18": "<string>",
        "customTag19": "<string>",
        "customTag20": "<string>",
        "experimentRunID": "<string>",
        "experimentVariantID": "<string>"
    },
    "series": ["<string>"],
    "display": True,
    "evidence": [],
    "refs": [{ "value": "<string>" }],
    "externalKey": "release-2026.10.1",
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    headline: '<string>',
    description: '<string>',
    dateFrom: '2026-09-17T09:45:00',
    dateTo: '2026-09-21T18:00:00',
    approximate: true,
    reading: '<string>',
    scope: {
      applicationID: '<string>',
      os: '<string>',
      osVersion: '<string>',
      browser: '<string>',
      customTag1: '<string>',
      customTag2: '<string>',
      customTag3: '<string>',
      customTag4: '<string>',
      customTag5: '<string>',
      customTag6: '<string>',
      customTag7: '<string>',
      customTag8: '<string>',
      customTag9: '<string>',
      customTag10: '<string>',
      customTag11: '<string>',
      customTag12: '<string>',
      customTag13: '<string>',
      customTag14: '<string>',
      customTag15: '<string>',
      customTag16: '<string>',
      customTag17: '<string>',
      customTag18: '<string>',
      customTag19: '<string>',
      customTag20: '<string>',
      experimentRunID: '<string>',
      experimentVariantID: '<string>'
    },
    series: ['<string>'],
    display: true,
    evidence: [],
    refs: [{value: '<string>'}],
    externalKey: 'release-2026.10.1',
    note: '<string>'
  })
};

fetch('https://api.cloud.corbado.io/v1/observe/annotations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloud.corbado.io/v1/observe/annotations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'headline' => '<string>',
    'description' => '<string>',
    'dateFrom' => '2026-09-17T09:45:00',
    'dateTo' => '2026-09-21T18:00:00',
    'approximate' => true,
    'reading' => '<string>',
    'scope' => [
        'applicationID' => '<string>',
        'os' => '<string>',
        'osVersion' => '<string>',
        'browser' => '<string>',
        'customTag1' => '<string>',
        'customTag2' => '<string>',
        'customTag3' => '<string>',
        'customTag4' => '<string>',
        'customTag5' => '<string>',
        'customTag6' => '<string>',
        'customTag7' => '<string>',
        'customTag8' => '<string>',
        'customTag9' => '<string>',
        'customTag10' => '<string>',
        'customTag11' => '<string>',
        'customTag12' => '<string>',
        'customTag13' => '<string>',
        'customTag14' => '<string>',
        'customTag15' => '<string>',
        'customTag16' => '<string>',
        'customTag17' => '<string>',
        'customTag18' => '<string>',
        'customTag19' => '<string>',
        'customTag20' => '<string>',
        'experimentRunID' => '<string>',
        'experimentVariantID' => '<string>'
    ],
    'series' => [
        '<string>'
    ],
    'display' => true,
    'evidence' => [
        
    ],
    'refs' => [
        [
                'value' => '<string>'
        ]
    ],
    'externalKey' => 'release-2026.10.1',
    'note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloud.corbado.io/v1/observe/annotations"

	payload := strings.NewReader("{\n  \"headline\": \"<string>\",\n  \"description\": \"<string>\",\n  \"dateFrom\": \"2026-09-17T09:45:00\",\n  \"dateTo\": \"2026-09-21T18:00:00\",\n  \"approximate\": true,\n  \"reading\": \"<string>\",\n  \"scope\": {\n    \"applicationID\": \"<string>\",\n    \"os\": \"<string>\",\n    \"osVersion\": \"<string>\",\n    \"browser\": \"<string>\",\n    \"customTag1\": \"<string>\",\n    \"customTag2\": \"<string>\",\n    \"customTag3\": \"<string>\",\n    \"customTag4\": \"<string>\",\n    \"customTag5\": \"<string>\",\n    \"customTag6\": \"<string>\",\n    \"customTag7\": \"<string>\",\n    \"customTag8\": \"<string>\",\n    \"customTag9\": \"<string>\",\n    \"customTag10\": \"<string>\",\n    \"customTag11\": \"<string>\",\n    \"customTag12\": \"<string>\",\n    \"customTag13\": \"<string>\",\n    \"customTag14\": \"<string>\",\n    \"customTag15\": \"<string>\",\n    \"customTag16\": \"<string>\",\n    \"customTag17\": \"<string>\",\n    \"customTag18\": \"<string>\",\n    \"customTag19\": \"<string>\",\n    \"customTag20\": \"<string>\",\n    \"experimentRunID\": \"<string>\",\n    \"experimentVariantID\": \"<string>\"\n  },\n  \"series\": [\n    \"<string>\"\n  ],\n  \"display\": true,\n  \"evidence\": [],\n  \"refs\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"externalKey\": \"release-2026.10.1\",\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloud.corbado.io/v1/observe/annotations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"headline\": \"<string>\",\n  \"description\": \"<string>\",\n  \"dateFrom\": \"2026-09-17T09:45:00\",\n  \"dateTo\": \"2026-09-21T18:00:00\",\n  \"approximate\": true,\n  \"reading\": \"<string>\",\n  \"scope\": {\n    \"applicationID\": \"<string>\",\n    \"os\": \"<string>\",\n    \"osVersion\": \"<string>\",\n    \"browser\": \"<string>\",\n    \"customTag1\": \"<string>\",\n    \"customTag2\": \"<string>\",\n    \"customTag3\": \"<string>\",\n    \"customTag4\": \"<string>\",\n    \"customTag5\": \"<string>\",\n    \"customTag6\": \"<string>\",\n    \"customTag7\": \"<string>\",\n    \"customTag8\": \"<string>\",\n    \"customTag9\": \"<string>\",\n    \"customTag10\": \"<string>\",\n    \"customTag11\": \"<string>\",\n    \"customTag12\": \"<string>\",\n    \"customTag13\": \"<string>\",\n    \"customTag14\": \"<string>\",\n    \"customTag15\": \"<string>\",\n    \"customTag16\": \"<string>\",\n    \"customTag17\": \"<string>\",\n    \"customTag18\": \"<string>\",\n    \"customTag19\": \"<string>\",\n    \"customTag20\": \"<string>\",\n    \"experimentRunID\": \"<string>\",\n    \"experimentVariantID\": \"<string>\"\n  },\n  \"series\": [\n    \"<string>\"\n  ],\n  \"display\": true,\n  \"evidence\": [],\n  \"refs\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"externalKey\": \"release-2026.10.1\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloud.corbado.io/v1/observe/annotations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"headline\": \"<string>\",\n  \"description\": \"<string>\",\n  \"dateFrom\": \"2026-09-17T09:45:00\",\n  \"dateTo\": \"2026-09-21T18:00:00\",\n  \"approximate\": true,\n  \"reading\": \"<string>\",\n  \"scope\": {\n    \"applicationID\": \"<string>\",\n    \"os\": \"<string>\",\n    \"osVersion\": \"<string>\",\n    \"browser\": \"<string>\",\n    \"customTag1\": \"<string>\",\n    \"customTag2\": \"<string>\",\n    \"customTag3\": \"<string>\",\n    \"customTag4\": \"<string>\",\n    \"customTag5\": \"<string>\",\n    \"customTag6\": \"<string>\",\n    \"customTag7\": \"<string>\",\n    \"customTag8\": \"<string>\",\n    \"customTag9\": \"<string>\",\n    \"customTag10\": \"<string>\",\n    \"customTag11\": \"<string>\",\n    \"customTag12\": \"<string>\",\n    \"customTag13\": \"<string>\",\n    \"customTag14\": \"<string>\",\n    \"customTag15\": \"<string>\",\n    \"customTag16\": \"<string>\",\n    \"customTag17\": \"<string>\",\n    \"customTag18\": \"<string>\",\n    \"customTag19\": \"<string>\",\n    \"customTag20\": \"<string>\",\n    \"experimentRunID\": \"<string>\",\n    \"experimentVariantID\": \"<string>\"\n  },\n  \"series\": [\n    \"<string>\"\n  ],\n  \"display\": true,\n  \"evidence\": [],\n  \"refs\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"externalKey\": \"release-2026.10.1\",\n  \"note\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "kind": "event",
  "platform": true,
  "headline": "<string>",
  "approximate": true,
  "display": true,
  "source": "manual",
  "createdMs": 123,
  "updatedMs": 123,
  "description": "<string>",
  "dateFrom": "<string>",
  "dateTo": "<string>",
  "datePrecision": "month",
  "dateFromMs": 123,
  "dateToMs": 123,
  "status": "open",
  "effect": "context",
  "reading": "<string>",
  "scope": {
    "applicationID": "<string>",
    "os": "<string>",
    "osVersion": "<string>",
    "browser": "<string>",
    "customTag1": "<string>",
    "customTag2": "<string>",
    "customTag3": "<string>",
    "customTag4": "<string>",
    "customTag5": "<string>",
    "customTag6": "<string>",
    "customTag7": "<string>",
    "customTag8": "<string>",
    "customTag9": "<string>",
    "customTag10": "<string>",
    "customTag11": "<string>",
    "customTag12": "<string>",
    "customTag13": "<string>",
    "customTag14": "<string>",
    "customTag15": "<string>",
    "customTag16": "<string>",
    "customTag17": "<string>",
    "customTag18": "<string>",
    "customTag19": "<string>",
    "customTag20": "<string>",
    "experimentRunID": "<string>",
    "experimentVariantID": "<string>"
  },
  "series": [
    "<string>"
  ],
  "evidence": [
    "code"
  ],
  "refs": [
    {
      "type": "finding",
      "value": "<string>"
    }
  ],
  "externalKey": "<string>"
}

{
  "error": {
    "message": "Validation failed",
    "details": [
      {
        "field": "projectID",
        "message": "required"
      }
    ]
  }
}

Annotations

Create annotation

Creates an annotation: one item of the project’s memory, the context needed to read its data correctly.

The kind decides which fields apply:

event: something changed (dateFrom required); may carry effect and reading.
period: something held over a span (dateFrom required, dateTo optional, absent = ongoing); may carry effect and reading.
setup, interpretation, constraint: facts, reading rules and binding data rules; no dates.
follow-up: an unknown or open work with status; dateFrom is when it becomes actionable.

Dates are local times in project time: YYYY-MM, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM:SS; the format sets the precision. dateTo is inclusive and must use the same format as dateFrom. Do not put metric values into annotations; they change and mislead.

Responds 409 when another annotation of the project already uses externalKey.

Required API key permission: observe:annotations:write.

POST

observe

annotations

Create annotation

curl --request POST \
  --url https://api.cloud.corbado.io/v1/observe/annotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "headline": "<string>",
  "description": "<string>",
  "dateFrom": "2026-09-17T09:45:00",
  "dateTo": "2026-09-21T18:00:00",
  "approximate": true,
  "reading": "<string>",
  "scope": {
    "applicationID": "<string>",
    "os": "<string>",
    "osVersion": "<string>",
    "browser": "<string>",
    "customTag1": "<string>",
    "customTag2": "<string>",
    "customTag3": "<string>",
    "customTag4": "<string>",
    "customTag5": "<string>",
    "customTag6": "<string>",
    "customTag7": "<string>",
    "customTag8": "<string>",
    "customTag9": "<string>",
    "customTag10": "<string>",
    "customTag11": "<string>",
    "customTag12": "<string>",
    "customTag13": "<string>",
    "customTag14": "<string>",
    "customTag15": "<string>",
    "customTag16": "<string>",
    "customTag17": "<string>",
    "customTag18": "<string>",
    "customTag19": "<string>",
    "customTag20": "<string>",
    "experimentRunID": "<string>",
    "experimentVariantID": "<string>"
  },
  "series": [
    "<string>"
  ],
  "display": true,
  "evidence": [],
  "refs": [
    {
      "value": "<string>"
    }
  ],
  "externalKey": "release-2026.10.1",
  "note": "<string>"
}
'

import requests

url = "https://api.cloud.corbado.io/v1/observe/annotations"

payload = {
    "headline": "<string>",
    "description": "<string>",
    "dateFrom": "2026-09-17T09:45:00",
    "dateTo": "2026-09-21T18:00:00",
    "approximate": True,
    "reading": "<string>",
    "scope": {
        "applicationID": "<string>",
        "os": "<string>",
        "osVersion": "<string>",
        "browser": "<string>",
        "customTag1": "<string>",
        "customTag2": "<string>",
        "customTag3": "<string>",
        "customTag4": "<string>",
        "customTag5": "<string>",
        "customTag6": "<string>",
        "customTag7": "<string>",
        "customTag8": "<string>",
        "customTag9": "<string>",
        "customTag10": "<string>",
        "customTag11": "<string>",
        "customTag12": "<string>",
        "customTag13": "<string>",
        "customTag14": "<string>",
        "customTag15": "<string>",
        "customTag16": "<string>",
        "customTag17": "<string>",
        "customTag18": "<string>",
        "customTag19": "<string>",
        "customTag20": "<string>",
        "experimentRunID": "<string>",
        "experimentVariantID": "<string>"
    },
    "series": ["<string>"],
    "display": True,
    "evidence": [],
    "refs": [{ "value": "<string>" }],
    "externalKey": "release-2026.10.1",
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    headline: '<string>',
    description: '<string>',
    dateFrom: '2026-09-17T09:45:00',
    dateTo: '2026-09-21T18:00:00',
    approximate: true,
    reading: '<string>',
    scope: {
      applicationID: '<string>',
      os: '<string>',
      osVersion: '<string>',
      browser: '<string>',
      customTag1: '<string>',
      customTag2: '<string>',
      customTag3: '<string>',
      customTag4: '<string>',
      customTag5: '<string>',
      customTag6: '<string>',
      customTag7: '<string>',
      customTag8: '<string>',
      customTag9: '<string>',
      customTag10: '<string>',
      customTag11: '<string>',
      customTag12: '<string>',
      customTag13: '<string>',
      customTag14: '<string>',
      customTag15: '<string>',
      customTag16: '<string>',
      customTag17: '<string>',
      customTag18: '<string>',
      customTag19: '<string>',
      customTag20: '<string>',
      experimentRunID: '<string>',
      experimentVariantID: '<string>'
    },
    series: ['<string>'],
    display: true,
    evidence: [],
    refs: [{value: '<string>'}],
    externalKey: 'release-2026.10.1',
    note: '<string>'
  })
};

fetch('https://api.cloud.corbado.io/v1/observe/annotations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloud.corbado.io/v1/observe/annotations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'headline' => '<string>',
    'description' => '<string>',
    'dateFrom' => '2026-09-17T09:45:00',
    'dateTo' => '2026-09-21T18:00:00',
    'approximate' => true,
    'reading' => '<string>',
    'scope' => [
        'applicationID' => '<string>',
        'os' => '<string>',
        'osVersion' => '<string>',
        'browser' => '<string>',
        'customTag1' => '<string>',
        'customTag2' => '<string>',
        'customTag3' => '<string>',
        'customTag4' => '<string>',
        'customTag5' => '<string>',
        'customTag6' => '<string>',
        'customTag7' => '<string>',
        'customTag8' => '<string>',
        'customTag9' => '<string>',
        'customTag10' => '<string>',
        'customTag11' => '<string>',
        'customTag12' => '<string>',
        'customTag13' => '<string>',
        'customTag14' => '<string>',
        'customTag15' => '<string>',
        'customTag16' => '<string>',
        'customTag17' => '<string>',
        'customTag18' => '<string>',
        'customTag19' => '<string>',
        'customTag20' => '<string>',
        'experimentRunID' => '<string>',
        'experimentVariantID' => '<string>'
    ],
    'series' => [
        '<string>'
    ],
    'display' => true,
    'evidence' => [
        
    ],
    'refs' => [
        [
                'value' => '<string>'
        ]
    ],
    'externalKey' => 'release-2026.10.1',
    'note' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloud.corbado.io/v1/observe/annotations"

	payload := strings.NewReader("{\n  \"headline\": \"<string>\",\n  \"description\": \"<string>\",\n  \"dateFrom\": \"2026-09-17T09:45:00\",\n  \"dateTo\": \"2026-09-21T18:00:00\",\n  \"approximate\": true,\n  \"reading\": \"<string>\",\n  \"scope\": {\n    \"applicationID\": \"<string>\",\n    \"os\": \"<string>\",\n    \"osVersion\": \"<string>\",\n    \"browser\": \"<string>\",\n    \"customTag1\": \"<string>\",\n    \"customTag2\": \"<string>\",\n    \"customTag3\": \"<string>\",\n    \"customTag4\": \"<string>\",\n    \"customTag5\": \"<string>\",\n    \"customTag6\": \"<string>\",\n    \"customTag7\": \"<string>\",\n    \"customTag8\": \"<string>\",\n    \"customTag9\": \"<string>\",\n    \"customTag10\": \"<string>\",\n    \"customTag11\": \"<string>\",\n    \"customTag12\": \"<string>\",\n    \"customTag13\": \"<string>\",\n    \"customTag14\": \"<string>\",\n    \"customTag15\": \"<string>\",\n    \"customTag16\": \"<string>\",\n    \"customTag17\": \"<string>\",\n    \"customTag18\": \"<string>\",\n    \"customTag19\": \"<string>\",\n    \"customTag20\": \"<string>\",\n    \"experimentRunID\": \"<string>\",\n    \"experimentVariantID\": \"<string>\"\n  },\n  \"series\": [\n    \"<string>\"\n  ],\n  \"display\": true,\n  \"evidence\": [],\n  \"refs\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"externalKey\": \"release-2026.10.1\",\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloud.corbado.io/v1/observe/annotations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"headline\": \"<string>\",\n  \"description\": \"<string>\",\n  \"dateFrom\": \"2026-09-17T09:45:00\",\n  \"dateTo\": \"2026-09-21T18:00:00\",\n  \"approximate\": true,\n  \"reading\": \"<string>\",\n  \"scope\": {\n    \"applicationID\": \"<string>\",\n    \"os\": \"<string>\",\n    \"osVersion\": \"<string>\",\n    \"browser\": \"<string>\",\n    \"customTag1\": \"<string>\",\n    \"customTag2\": \"<string>\",\n    \"customTag3\": \"<string>\",\n    \"customTag4\": \"<string>\",\n    \"customTag5\": \"<string>\",\n    \"customTag6\": \"<string>\",\n    \"customTag7\": \"<string>\",\n    \"customTag8\": \"<string>\",\n    \"customTag9\": \"<string>\",\n    \"customTag10\": \"<string>\",\n    \"customTag11\": \"<string>\",\n    \"customTag12\": \"<string>\",\n    \"customTag13\": \"<string>\",\n    \"customTag14\": \"<string>\",\n    \"customTag15\": \"<string>\",\n    \"customTag16\": \"<string>\",\n    \"customTag17\": \"<string>\",\n    \"customTag18\": \"<string>\",\n    \"customTag19\": \"<string>\",\n    \"customTag20\": \"<string>\",\n    \"experimentRunID\": \"<string>\",\n    \"experimentVariantID\": \"<string>\"\n  },\n  \"series\": [\n    \"<string>\"\n  ],\n  \"display\": true,\n  \"evidence\": [],\n  \"refs\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"externalKey\": \"release-2026.10.1\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloud.corbado.io/v1/observe/annotations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"headline\": \"<string>\",\n  \"description\": \"<string>\",\n  \"dateFrom\": \"2026-09-17T09:45:00\",\n  \"dateTo\": \"2026-09-21T18:00:00\",\n  \"approximate\": true,\n  \"reading\": \"<string>\",\n  \"scope\": {\n    \"applicationID\": \"<string>\",\n    \"os\": \"<string>\",\n    \"osVersion\": \"<string>\",\n    \"browser\": \"<string>\",\n    \"customTag1\": \"<string>\",\n    \"customTag2\": \"<string>\",\n    \"customTag3\": \"<string>\",\n    \"customTag4\": \"<string>\",\n    \"customTag5\": \"<string>\",\n    \"customTag6\": \"<string>\",\n    \"customTag7\": \"<string>\",\n    \"customTag8\": \"<string>\",\n    \"customTag9\": \"<string>\",\n    \"customTag10\": \"<string>\",\n    \"customTag11\": \"<string>\",\n    \"customTag12\": \"<string>\",\n    \"customTag13\": \"<string>\",\n    \"customTag14\": \"<string>\",\n    \"customTag15\": \"<string>\",\n    \"customTag16\": \"<string>\",\n    \"customTag17\": \"<string>\",\n    \"customTag18\": \"<string>\",\n    \"customTag19\": \"<string>\",\n    \"customTag20\": \"<string>\",\n    \"experimentRunID\": \"<string>\",\n    \"experimentVariantID\": \"<string>\"\n  },\n  \"series\": [\n    \"<string>\"\n  ],\n  \"display\": true,\n  \"evidence\": [],\n  \"refs\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"externalKey\": \"release-2026.10.1\",\n  \"note\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "kind": "event",
  "platform": true,
  "headline": "<string>",
  "approximate": true,
  "display": true,
  "source": "manual",
  "createdMs": 123,
  "updatedMs": 123,
  "description": "<string>",
  "dateFrom": "<string>",
  "dateTo": "<string>",
  "datePrecision": "month",
  "dateFromMs": 123,
  "dateToMs": 123,
  "status": "open",
  "effect": "context",
  "reading": "<string>",
  "scope": {
    "applicationID": "<string>",
    "os": "<string>",
    "osVersion": "<string>",
    "browser": "<string>",
    "customTag1": "<string>",
    "customTag2": "<string>",
    "customTag3": "<string>",
    "customTag4": "<string>",
    "customTag5": "<string>",
    "customTag6": "<string>",
    "customTag7": "<string>",
    "customTag8": "<string>",
    "customTag9": "<string>",
    "customTag10": "<string>",
    "customTag11": "<string>",
    "customTag12": "<string>",
    "customTag13": "<string>",
    "customTag14": "<string>",
    "customTag15": "<string>",
    "customTag16": "<string>",
    "customTag17": "<string>",
    "customTag18": "<string>",
    "customTag19": "<string>",
    "customTag20": "<string>",
    "experimentRunID": "<string>",
    "experimentVariantID": "<string>"
  },
  "series": [
    "<string>"
  ],
  "evidence": [
    "code"
  ],
  "refs": [
    {
      "type": "finding",
      "value": "<string>"
    }
  ],
  "externalKey": "<string>"
}

{
  "error": {
    "message": "Validation failed",
    "details": [
      {
        "field": "projectID",
        "message": "required"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server.

Body

application/json

kind

enum<string>

required

Kind of the annotation.

Available options:

event,

period,

setup,

interpretation,

constraint,

follow-up

headline

string

required

One line saying what the annotation records.

description

string

Optional Markdown body with details.

dateFrom

string

Date in project time: YYYY-MM, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM:SS; the format sets the precision. Required for events and periods, optional for follow-ups (not before), not allowed otherwise.

Pattern: ^\d{4}-\d{2}(-\d{2}(T\d{2}(:\d{2}:\d{2})?)?)?$

Example:

"2026-09-17T09:45:00"

dateTo

string

Last unit a period covers (inclusive), in the same format as dateFrom. Absent means ongoing.

Pattern: ^\d{4}-\d{2}(-\d{2}(T\d{2}(:\d{2}:\d{2})?)?)?$

Example:

"2026-09-21T18:00:00"

approximate

boolean

The date is not exact. Requires a date.

status

enum<string>

Follow-ups only; defaults to open.

Available options:

open,

done

effect

enum<string>

Events and periods only; defaults to context.

Available options:

context,

boundary,

degraded,

broken,

missing

reading

string

Events and periods only. The reading rule this date brings, e.g. "Compare identifier modality only within one side of this date".

scope

object

Narrows what the annotation applies to, by time-series dimension. Absent means the whole project.

Show child attributes

series

string[]

Time series the annotation is mainly about, by name. Absent means all.

Maximum array length: 50

display

boolean

False hides the annotation from charts; documents always contain it. Defaults to true, and to false for source system unless an effect other than context is set.

source

enum<string>

Who wrote the annotation. Defaults to manual from the developer panel and agent from an API key.

Available options:

manual,

agent,

system

evidence

enum<string>[]

Kinds of evidence the annotation rests on. Absent means unverified.

Maximum array length: 4

Kind of evidence an annotation rests on.

Available options:

code,

trace,

data,

customer

refs

object[]

External references. Findings and annotations must exist in the project.

Maximum array length: 50

Show child attributes

externalKey

string

Your stable key for the annotation, unique per project, e.g. a release tag. Lowercase letters, digits, ., _ and -. To create or update by key in one call, use PUT /observe/annotations/byExternalKey/{externalKey}.

Example:

"release-2026.10.1"

note

string

Note stored in the annotation's history. Required when a follow-up is closed.

Response

Annotation created.

string

required

Annotation ID (format ann-<number>).

kind

enum<string>

required

What the annotation records: event something changed, period something held over a span, setup a fact about how the project works, interpretation how to read the data, constraint which data may be used, follow-up an unknown or open work.

Available options:

event,

period,

setup,

interpretation,

constraint,

follow-up

platform

boolean

required

Platform annotation that applies to every project; managed by Corbado.

headline

string

required

One line saying what the annotation records.

approximate

boolean

required

The date is not exact.

display

boolean

required

Shown on charts.

source

enum<string>

required

Who wrote the annotation or made a change.

Available options:

manual,

agent,

system

createdMs

integer<int64>

required

Creation time in milliseconds since epoch.

updatedMs

integer<int64>

required

Last update time in milliseconds since epoch.

description

string

Optional Markdown body with details.

dateFrom

string

Date as stated, in project time (UTC for platform annotations), in the format of its precision.

dateTo

string

Last unit a period covers (inclusive), in the same format. Absent on an ongoing period.

datePrecision

enum<string>

Unit the annotation's dates were stated in.

Available options:

month,

date,

hour,

datetime

dateFromMs

integer<int64>

Start of dateFrom in milliseconds since epoch.

dateToMs

integer<int64>

End of the span (exclusive) in milliseconds since epoch.

status

enum<string>

Where a follow-up stands.

Available options:

open,

done

effect

enum<string>

How an event or period changes the reading of the data: context background only, boundary compare only within one side, degraded data partly wrong, broken data wrong, missing no data.

Available options:

context,

boundary,

degraded,

broken,

missing

reading

string

Reading rule this date brings (events and periods).

scope

object

Narrows what the annotation applies to, by time-series dimension. Absent means the whole project.

Show child attributes

series

string[]

Maximum array length: 50

evidence

enum<string>[]

Maximum array length: 4

Kind of evidence an annotation rests on.

Available options:

code,

trace,

data,

customer

refs

object[]

Maximum array length: 50

Show child attributes

externalKey

string

Overview

Corbado Observe

Corbado Connect

Create annotation

Authorizations

Body

Response