Create or update annotation by external key

curl --request PUT \
  --url https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey} \
  --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>",
    "experimentRunID": "<string>",
    "experimentVariantID": "<string>"
  },
  "series": [
    "<string>"
  ],
  "display": true,
  "evidence": [],
  "refs": [
    {
      "value": "<string>"
    }
  ],
  "note": "<string>"
}
'

import requests

url = "https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey}"

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>",
        "experimentRunID": "<string>",
        "experimentVariantID": "<string>"
    },
    "series": ["<string>"],
    "display": True,
    "evidence": [],
    "refs": [{ "value": "<string>" }],
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  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>',
      experimentRunID: '<string>',
      experimentVariantID: '<string>'
    },
    series: ['<string>'],
    display: true,
    evidence: [],
    refs: [{value: '<string>'}],
    note: '<string>'
  })
};

fetch('https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey}', 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/byExternalKey/{externalKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  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>',
        'experimentRunID' => '<string>',
        'experimentVariantID' => '<string>'
    ],
    'series' => [
        '<string>'
    ],
    'display' => true,
    'evidence' => [
        
    ],
    'refs' => [
        [
                'value' => '<string>'
        ]
    ],
    '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/byExternalKey/{externalKey}"

	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    \"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  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey}")
  .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    \"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  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.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    \"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  \"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>",
    "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 or update annotation by external key

Creates the project’s annotation with this external key on the first call and replaces its content on later calls, so a writer that runs repeatedly (a release pipeline, a scheduled agent) keeps one annotation per key. Replacing follows the rules of PUT /observe/annotations/{annotationID}. The history records created or the kind of change.

Concurrent first calls with the same key can answer 409; retrying updates the annotation then created.

Required API key permission: observe:annotations:write.

PUT

observe

annotations

byExternalKey

{externalKey}

Create or update annotation by external key

curl --request PUT \
  --url https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey} \
  --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>",
    "experimentRunID": "<string>",
    "experimentVariantID": "<string>"
  },
  "series": [
    "<string>"
  ],
  "display": true,
  "evidence": [],
  "refs": [
    {
      "value": "<string>"
    }
  ],
  "note": "<string>"
}
'

import requests

url = "https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey}"

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>",
        "experimentRunID": "<string>",
        "experimentVariantID": "<string>"
    },
    "series": ["<string>"],
    "display": True,
    "evidence": [],
    "refs": [{ "value": "<string>" }],
    "note": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  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>',
      experimentRunID: '<string>',
      experimentVariantID: '<string>'
    },
    series: ['<string>'],
    display: true,
    evidence: [],
    refs: [{value: '<string>'}],
    note: '<string>'
  })
};

fetch('https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey}', 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/byExternalKey/{externalKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  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>',
        'experimentRunID' => '<string>',
        'experimentVariantID' => '<string>'
    ],
    'series' => [
        '<string>'
    ],
    'display' => true,
    'evidence' => [
        
    ],
    'refs' => [
        [
                'value' => '<string>'
        ]
    ],
    '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/byExternalKey/{externalKey}"

	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    \"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  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://api.cloud.corbado.io/v1/observe/annotations/byExternalKey/{externalKey}")
  .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    \"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  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.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    \"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  \"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>",
    "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.

Path Parameters

externalKey

string

required

External key, unique per project. Lowercase letters, digits, ., _ and -, at most 128 characters.

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

note

string

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

Response

Annotation created or updated.

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 or update annotation by external key

Authorizations

Path Parameters

Body

Response