---
title: "Create an annotation configuration"
method: POST
path: "/v1/annotation_configs"
tags: ["annotation_configs"]
---

# Create an annotation configuration

`POST /v1/annotation_configs`

## Request body

- union
  - CategoricalAnnotationConfigData
    - `name` string, required
    - `type` 'CATEGORICAL', required
    - `description` string, nullable
    - `optimization_direction` 'MINIMIZE' | 'MAXIMIZE' | 'NONE', required
    - `values` CategoricalAnnotationValue[], required
      - `label` string, required
      - `score` number, nullable
  - ContinuousAnnotationConfigData
    - `name` string, required
    - `type` 'CONTINUOUS', required
    - `description` string, nullable
    - `optimization_direction` 'MINIMIZE' | 'MAXIMIZE' | 'NONE', required
    - `lower_bound` number, nullable
    - `upper_bound` number, nullable
  - FreeformAnnotationConfigData
    - `name` string, required
    - `type` 'FREEFORM', required
    - `description` string, nullable
    - `optimization_direction` 'MINIMIZE' | 'MAXIMIZE' | 'NONE'
    - `threshold` number, nullable
    - `lower_bound` number, nullable
    - `upper_bound` number, nullable

## Response `200`

Successful Response

- CreateAnnotationConfigResponseBody
  - `data` union, required
    - CategoricalAnnotationConfig
      - `name` string, required
      - `type` 'CATEGORICAL', required
      - `description` string, nullable
      - `optimization_direction` 'MINIMIZE' | 'MAXIMIZE' | 'NONE', required
      - `values` CategoricalAnnotationValue[], required
        - `label` string, required
        - `score` number, nullable
      - `id` string, required
    - ContinuousAnnotationConfig
      - `name` string, required
      - `type` 'CONTINUOUS', required
      - `description` string, nullable
      - `optimization_direction` 'MINIMIZE' | 'MAXIMIZE' | 'NONE', required
      - `lower_bound` number, nullable
      - `upper_bound` number, nullable
      - `id` string, required
    - FreeformAnnotationConfig
      - `name` string, required
      - `type` 'FREEFORM', required
      - `description` string, nullable
      - `optimization_direction` 'MINIMIZE' | 'MAXIMIZE' | 'NONE'
      - `threshold` number, nullable
      - `lower_bound` number, nullable
      - `upper_bound` number, nullable
      - `id` string, required

## Other responses

- `403` — Forbidden
- `422` — Validation Error

## Changes

- **2026-07-17** `5b062a93db67` — 1 info
  - api operation id `create_annotation_config_v1_annotation_configs_post` removed and replaced with `createAnnotationConfig`
- **2026-05-21** `ea31306c1333` — 8 info
  - added the new optional request property `oneOf[subschema #3: FreeformAnnotationConfigData]/lower_bound`
  - added the new optional request property `oneOf[subschema #3: FreeformAnnotationConfigData]/optimization_direction`
  - added the new optional request property `oneOf[subschema #3: FreeformAnnotationConfigData]/threshold`
  - added the new optional request property `oneOf[subschema #3: FreeformAnnotationConfigData]/upper_bound`
  - …4 more
- **2026-04-29** `c81391216eb5` — 8 warning
  - removed the request property `oneOf[subschema #3: FreeformAnnotationConfigData]/lower_bound`
  - removed the request property `oneOf[subschema #3: FreeformAnnotationConfigData]/optimization_direction`
  - removed the request property `oneOf[subschema #3: FreeformAnnotationConfigData]/threshold`
  - removed the request property `oneOf[subschema #3: FreeformAnnotationConfigData]/upper_bound`
  - …4 more

[Change history](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/changes/v1/annotation_configs/post.md)

---

[API](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/b43e9d4f06e0/schema)