Create annotation - Automate.ax

axiom.createAnnotation creates an annotation across one or more datasets. type accepts lowercase letters, digits, and hyphens; omit time to use Axiom’s current time.

automations/axiom-create-annotation.automation.ts

import { automation, onHttpRequest } from "automate.ax"
import { axiom } from "automate.ax/axiom"

export default automation("Create annotation", () => {
  onHttpRequest({ scope: "automation" })
  axiom.createAnnotation({
    datasets: ["production"],
    type: "deploy",
    title: "Version 2.4 deployed",
    time: "2026-08-30T18:00:00Z",
  })
})

Inputs

Input	Required	Description
`datasets`	Yes	One or more dataset names or IDs.
`type`	Yes	Category containing only lowercase letters, digits, and hyphens, up to 256 characters.
`time`	No	Start time. Axiom uses the current time when omitted.
`endTime`	No	End time for a ranged annotation.
`title`	No	Display title, up to 256 characters.
`description`	No	Detail text, up to 512 characters.
`url`	No	Related URL, up to 512 characters.

Output

Returns the created annotation with its id, datasets, type, start time, and any optional display fields.

Permission and failures

The API token needs the organization-level annotations|create capability. Axiom rejects inaccessible datasets, invalid time values, and annotation fields outside their documented constraints. Authentication and permission failures are returned as action errors.