Create annotation

POST/v2/annotations

Creates an annotation on one or more existing datasets. If you omit time, Axiom uses the time of the request. time can't be in the future.

Body

application/json

Property	Type	Description
`datasets`	`string[]`Required	array<string> of dataset names for which the annotation appears on charts
`description`	`string`	Explanation of the event the annotation marks on the charts
`endTime`	`string<date-time>`	End time of the annotation
`time`	`string<date-time>`	Time the annotation marks on the charts. If you don't include this field, Axiom assigns the time of the API request to the annotation.
`title`	`string`	Summary of the annotation that appears on the charts
`type`	`string`Required	Type of the event marked by the annotation. Use only alphanumeric characters or hyphens. For example, "production-deployment".
`url`	`string`	URL relevant for the event marked by the annotation. For example, link to GitHub pull request.

Request

curl -X POST 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"datasets":["string"],"description":"string","endTime":"2026-01-01T00:00:00Z","time":"2026-01-01T00:00:00Z","title":"string","type":"string","url":"string"}'

Try itRun this request against your Axiom organization

Credentials stay in this browser tab and are only sent to Axiom when you run the request.

API token RequiredRequest body application/json

Response

201Created annotation.

application/json

400Invalid annotation, for example an unknown dataset, a `time` in the future, or an `endTime` before `time`.

Property	Type	Description
`datasets`	`string[]`Required	array<string> of dataset names for which the annotation appears on charts
`description`	`string`	Explanation of the event the annotation marks on the charts
`endTime`	`string<date-time>`	End time of the annotation
`id`	`string`Required
`time`	`string<date-time>`Required	Time the annotation marks on the charts. If you don't include this field, Axiom assigns the time of the API request to the annotation.
`title`	`string`	Summary of the annotation that appears on the charts
`type`	`string`Required	Type of the event marked by the annotation. Use only alphanumeric characters or hyphens. For example, "production-deployment".
`url`	`string`	URL relevant for the event marked by the annotation. For example, link to GitHub pull request.