> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Create annotation

> Creates an annotation across one or more datasets.

`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.

```ts automations/axiom-create-annotation.automation.ts theme={null}
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.