Annotation Configs

The ax annotation-configs commands are currently in BETA. The API may change without notice. A one-time warning is emitted on first use.

The ax annotation-configs commands let you create, retrieve, and manage annotation configs on the Arize platform. Annotation configs define structured label schemas for human feedback and data curation.

`ax annotation-configs list`

List all annotation configs in a space.

ax annotation-configs list [--space <id>] [--name <filter>] [--limit <n>] [--cursor <cursor>] [--output <fmt>] [--verbose]

Option	Description
`--name`, `-n`	Case-insensitive substring filter on annotation config name
`--space`, `-s`	Space name or ID
`--limit`, `-l`	Maximum number of annotation configs to return (default: 15)
`--cursor`, `-c`	Pagination cursor for the next page
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples:

ax annotation-configs list --space sp_abc123
ax annotation-configs list --space sp_abc123 --output configs.json

`ax annotation-configs create`

Create a new annotation config. Three types are supported: CATEGORICAL, CONTINUOUS, and FREEFORM.

ax annotation-configs create --name <name> --space <id> --type <type> [type-specific options] [--output <fmt>] [--verbose]

Option	Description
`--name`, `-n`	Annotation config name (required; prompts if omitted)
`--space`, `-s`	Space name or ID (required; prompts if omitted)
`--type`, `-t`	Annotation config type: `CATEGORICAL`, `CONTINUOUS`, or `FREEFORM` (required; prompts if omitted)
`--min-score`	Minimum score (required for `CONTINUOUS` type)
`--max-score`	Maximum score (required for `CONTINUOUS` type)
`--value`	Label for `CATEGORICAL` type — repeat for multiple values (e.g. `--value good --value bad`)
`--optimization-direction`	`MAXIMIZE`, `MINIMIZE`, or `NONE`
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples: Categorical (discrete labels with optional scores):

ax annotation-configs create \
  --name "accuracy" \
  --space sp_abc123 \
  --type CATEGORICAL \
  --value accurate \
  --value inaccurate \
  --optimization-direction MAXIMIZE

Continuous (numeric score range):

ax annotation-configs create \
  --name "relevance" \
  --space sp_abc123 \
  --type CONTINUOUS \
  --min-score 0.0 \
  --max-score 1.0 \
  --optimization-direction MAXIMIZE

Freeform (free-text feedback, no scoring):

ax annotation-configs create \
  --name "reviewer-notes" \
  --space sp_abc123 \
  --type FREEFORM

`ax annotation-configs get`

Retrieve a single annotation config by name or ID.

ax annotation-configs get <name-or-id> [--space <name_or_id>] [--output <fmt>] [--verbose]

Option	Description
`--space`, `-s`	Space name or ID (required when using annotation config name instead of ID)
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples:

ax annotation-configs get ac_xyz789
ax annotation-configs get "accuracy" --space my-space

`ax annotation-configs update`

Update an annotation config. Choose the subcommand matching the config’s type: continuous, categorical, or freeform. Only the fields you pass are changed; omitted fields are left unchanged.

`ax annotation-configs update continuous`

ax annotation-configs update continuous <name-or-id> [--space <id>] [--new-name <name>] [--min-score <n>] [--max-score <n>] [--optimization-direction <dir>] [--output <fmt>] [--verbose]

Option	Description
`--space`, `-s`	Space name or ID (required when using a name instead of an ID)
`--new-name`	New name for the annotation config
`--min-score`	New minimum score
`--max-score`	New maximum score
`--optimization-direction`	New optimization direction (`MAXIMIZE`, `MINIMIZE`, or `NONE`)
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

`ax annotation-configs update categorical`

ax annotation-configs update categorical <name-or-id> [--space <id>] [--new-name <name>] [--value <label> ...] [--optimization-direction <dir>] [--output <fmt>] [--verbose]

Option	Description
`--space`, `-s`	Space name or ID (required when using a name instead of an ID)
`--new-name`	New name for the annotation config
`--value`	Replacement label value — repeat for multiple
`--optimization-direction`	New optimization direction (`MAXIMIZE`, `MINIMIZE`, or `NONE`)
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

`ax annotation-configs update freeform`

ax annotation-configs update freeform <name-or-id> [--space <id>] [--new-name <name>] [--output <fmt>] [--verbose]

Option	Description
`--space`, `-s`	Space name or ID (required when using a name instead of an ID)
`--new-name`	New name for the annotation config
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples:

ax annotation-configs update continuous relevance --max-score 5.0
ax annotation-configs update categorical accuracy --value accurate --value inaccurate
ax annotation-configs update freeform reviewer-notes --new-name "review-notes"

`ax annotation-configs delete`

Delete an annotation config by name or ID. This operation is irreversible.

ax annotation-configs delete <name-or-id> [--space <name_or_id>] [--force] [--verbose]

Option	Description
`--space`, `-s`	Space name or ID (required when using annotation config name instead of ID)
`--force`, `-f`	Skip the confirmation prompt
`--verbose`, `-v`	Enable verbose logs

Examples:

ax annotation-configs delete ac_xyz789 --force
ax annotation-configs delete "accuracy" --space my-space --force

API reference

API clients

`ax annotation-configs list`

`ax annotation-configs create`

`ax annotation-configs get`

`ax annotation-configs update`

`ax annotation-configs update continuous`

`ax annotation-configs update categorical`

`ax annotation-configs update freeform`

`ax annotation-configs delete`

​ax annotation-configs list

​ax annotation-configs create

​ax annotation-configs get

​ax annotation-configs update

​ax annotation-configs update continuous

​ax annotation-configs update categorical

​ax annotation-configs update freeform

​ax annotation-configs delete

`ax annotation-configs list`

`ax annotation-configs create`

`ax annotation-configs get`

`ax annotation-configs update`

`ax annotation-configs update continuous`

`ax annotation-configs update categorical`

`ax annotation-configs update freeform`

`ax annotation-configs delete`