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

# Create an annotation config

> Create a new annotation config.

**Payload Requirements**
- The annotation config name must be unique within the given space.

**Valid example**
```json
{
  "name": "my-annotation-config",
  "space_id": "spc_123",
  "annotation_config_type": "CATEGORICAL",
  "values": [
    {
      "label": "value1",
      "score": 0
    },
    {
      "label": "value2",
      "score": 1
    }
  ],
  "optimization_direction": "MAXIMIZE"
}
```

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml post /v2/annotation-configs
openapi: 3.0.3
info:
  title: Arize REST API
  version: 2.0.0
  description: |
    API specification for the backend data server. The API is hosted globally
    at https://api.arize.com/v2 or in your own environment.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - description: Global
    url: https://api.arize.com
  - description: Regional
    url: https://api.{region}.arize.com
    variables:
      region:
        default: eu-west-1a
        enum:
          - eu-west-1a
          - ca-central-1a
  - description: Custom Host
    url: https://{host}
    variables:
      host:
        default: api.arize.com
security:
  - bearerAuth: []
tags:
  - name: AI Integrations
    description: |
      AI integrations configure access to external LLM providers (e.g. OpenAI,
      Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
      entire account, a specific organization, or a specific space.
  - name: Annotation Configs
    description: >
      Annotation configs allow you to define consistent annotation schemas that

      can be reused across your workspace, ensuring evaluations are structured
      and

      comparable over time.
  - name: Annotation Queues
    description: >
      Annotation queues help you organize and manage human evaluation workflows.

      Use queues to assign spans or examples to annotators for review and
      labeling.
  - name: API Keys
    description: >
      API keys are used to authenticate requests to the Arize API. List your
      keys

      to view metadata; the raw secret is never returned after creation.
  - name: Audit Logs
    description: >
      Audit logs record authenticated user actions within an account, providing
      a

      chronological trail for security and compliance review. Access requires

      account admin privileges and audit logging to be enabled.
  - name: Datasets
    description: |
      Datasets are structured, version-controlled example collections you use to
      run, evaluate, and track LLM experiments.
  - name: Evaluators
    description: >
      Evaluators are reusable evaluation configurations used to assess the
      quality

      of LLM outputs. They can be template-based (using LLM judges) or
      code-based.
  - name: Experiments
    description: >
      Experiments let you systematically test prompt/model changes using
      datasets,

      tasks, and evaluators.
  - name: Integrations
    description: >
      Integrations configure access to external LLM providers (e.g. OpenAI,

      Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
      PagerDuty, Slack), and

      your own agents. Integrations can be scoped to the entire account, a
      specific

      organization, or a specific space.
  - name: Monitors
    description: >
      Monitors continuously track a metric over your model or LLM application
      data

      and alert you when it crosses a threshold. Each monitor watches a single

      metric - data quality, model performance, drift, a custom metric, or a

      tracing metric - and moves between statuses as the metric passes in and
      out of its 

      healthy range.
  - name: Organizations
    description: >
      Organizations are top-level containers within an Arize AX account for
      grouping spaces.
  - name: Projects
    description: |
      Projects represent LLM applications being monitored in Arize where you can
      observe traces and spans.
  - name: Prompts
    description: >
      Prompts are reusable, versioned templates for LLM interactions. Use
      prompts

      to standardize and manage how you interact with LLMs across your
      application.
  - name: Resource Restrictions
    description: |
      Endpoints for restricting and unrestricting resources (projects, models).
  - name: Role Bindings
    description: |
      Role bindings assign a role to a user on a resource. REST currently
      supports space- and project-scoped bindings.
  - name: Roles
    description: >
      Roles define sets of permissions that can be assigned to users within an

      account. Create custom roles to tailor access control to your team's
      needs.
  - name: Spaces
    description: >
      Spaces are containers within an organization for grouping related
      projects,

      datasets, and experiments, enabling collaboration or isolated
      experimentation

      with role-based access control.
  - name: Spans
    description: |
      Spans represent individual operations within a trace. A span captures the
      timing, status, and attributes of a single operation in your application.
  - name: Tasks
    description: |
      Tasks are configurable units of work that tie one or more evaluators to a
      data source (project or dataset). Use tasks to automate evaluation of LLM
      outputs, with support for continuous evaluation and backfill runs.
  - name: Traces
    description: |
      A trace is the collection of spans sharing a trace ID, representing a
      single end-to-end request through an LLM application. Use the Traces
      endpoint to retrieve traces with all of their spans in one call.
  - name: Users
    description: >
      Users represent members of an account. The Users endpoints allow creating,

      listing, updating (display name), and removing users from the account
      programmatically.
paths:
  /v2/annotation-configs:
    post:
      tags:
        - Annotation Configs
      summary: Create an annotation config
      description: >
        Create a new annotation config.


        **Payload Requirements**

        - The annotation config name must be unique within the given space.


        **Valid example**

        ```json

        {
          "name": "my-annotation-config",
          "space_id": "spc_123",
          "annotation_config_type": "CATEGORICAL",
          "values": [
            {
              "label": "value1",
              "score": 0
            },
            {
              "label": "value2",
              "score": 1
            }
          ],
          "optimization_direction": "MAXIMIZE"
        }

        ```


        <Note>This endpoint is in beta, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>
      operationId: create_annotation_config
      requestBody:
        $ref: '#/components/requestBodies/CreateAnnotationConfigRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/AnnotationConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  requestBodies:
    CreateAnnotationConfigRequestBody:
      description: Body containing annotation config creation parameters
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAnnotationConfigRequest'
          example:
            name: Accuracy
            space_id: space_12345
            annotation_config_type: CATEGORICAL
            values:
              - label: accurate
                score: 1
              - label: inaccurate
                score: 0
            optimization_direction: MAXIMIZE
  responses:
    AnnotationConfig:
      description: An annotation config object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnnotationConfig'
          example:
            id: QW5ub3RhdGlvbkNvbmZpZzoxMjM0NQ==
            name: quality-v2
            space_id: space_12345
            type: CATEGORICAL
            values:
              - label: good
                score: 1
              - label: bad
                score: 0
            optimization_direction: MAXIMIZE
            created_at: '2024-01-01T00:00:00Z'
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 400
            title: Invalid request parameters
            detail: The 'name' field is required and must be a non-empty string.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
    Unauthorized:
      description: Authentication is required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Authentication required
            detail: You must be authenticated to access this resource.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#authentication-required
    Forbidden:
      description: Insufficient permissions to access this resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Access forbidden
            detail: You do not have permission to access this resource.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 404
            title: Resource not found
            detail: The requested resource with ID '12345' was not found.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found
    Conflict:
      description: Resource conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 409
            title: Resource conflict
            detail: A resource with the given identifier already exists.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#resource-conflict
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 422
            title: Unprocessable Entity
            detail: One or more fields failed validation.
            instance: /resource/12345
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: |
            When throttled (429), how long to wait before retrying. Value is
            either a delta-seconds integer.
          schema:
            type: integer
            minimum: 0
          example: 42
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 429
            title: Rate limit exceeded
            detail: >-
              You have exceeded the allowed number of requests. Please try again
              later.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
  schemas:
    CreateAnnotationConfigRequest:
      required:
        - name
        - space_id
        - annotation_config_type
      properties:
        annotation_config_type:
          $ref: '#/components/schemas/AnnotationConfigType'
      discriminator:
        propertyName: annotation_config_type
        mapping:
          CONTINUOUS:
            $ref: '#/components/schemas/CreateContinuousAnnotationConfigRequest'
          CATEGORICAL:
            $ref: '#/components/schemas/CreateCategoricalAnnotationConfigRequest'
          FREEFORM:
            $ref: '#/components/schemas/CreateFreeformAnnotationConfigRequest'
      oneOf:
        - $ref: '#/components/schemas/CreateContinuousAnnotationConfigRequest'
        - $ref: '#/components/schemas/CreateCategoricalAnnotationConfigRequest'
        - $ref: '#/components/schemas/CreateFreeformAnnotationConfigRequest'
    AnnotationConfig:
      type: object
      additionalProperties: true
      discriminator:
        propertyName: type
        mapping:
          CONTINUOUS:
            $ref: '#/components/schemas/ContinuousAnnotationConfig'
          CATEGORICAL:
            $ref: '#/components/schemas/CategoricalAnnotationConfig'
          FREEFORM:
            $ref: '#/components/schemas/FreeformAnnotationConfig'
      oneOf:
        - $ref: '#/components/schemas/ContinuousAnnotationConfig'
        - $ref: '#/components/schemas/CategoricalAnnotationConfig'
        - $ref: '#/components/schemas/FreeformAnnotationConfig'
    Problem:
      type: object
      description: RFC 9457 Problem Details
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem
        type:
          type: string
          format: uri-reference
          description: A URI reference that identifies the problem type
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
        instance:
          type: string
          format: uri-reference
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
      required:
        - title
        - status
      additionalProperties: false
    AnnotationConfigType:
      type: string
      enum:
        - CONTINUOUS
        - CATEGORICAL
        - FREEFORM
      description: |
        The type of annotation config:
        - CONTINUOUS: a numeric score within a defined range
        - CATEGORICAL: a set of labeled values each with an optional score
        - FREEFORM: free-text annotation with no structured scoring
    CreateContinuousAnnotationConfigRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - space_id
        - annotation_config_type
        - minimum_score
        - maximum_score
      properties:
        name:
          type: string
          description: Name of the new annotation config
        space_id:
          type: string
          description: ID of the space the annotation config will belong to
        annotation_config_type:
          type: string
          enum:
            - CONTINUOUS
          description: Discriminator value identifying a continuous annotation config.
        minimum_score:
          type: number
          format: double
          description: The minimum score value
        maximum_score:
          type: number
          format: double
          description: The maximum score value
        optimization_direction:
          allOf:
            - $ref: '#/components/schemas/OptimizationDirection'
          default: NONE
          description: Direction for optimization. Defaults to `NONE` when omitted.
    CreateCategoricalAnnotationConfigRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - space_id
        - annotation_config_type
        - values
      properties:
        name:
          type: string
          description: Name of the new annotation config
        space_id:
          type: string
          description: ID of the space the annotation config will belong to
        annotation_config_type:
          type: string
          enum:
            - CATEGORICAL
          description: Discriminator value identifying a categorical annotation config.
        values:
          type: array
          description: An array of categorical annotation values
          items:
            $ref: '#/components/schemas/CategoricalAnnotationValue'
        optimization_direction:
          allOf:
            - $ref: '#/components/schemas/OptimizationDirection'
          default: NONE
          description: Direction for optimization. Defaults to `NONE` when omitted.
    CreateFreeformAnnotationConfigRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - space_id
        - annotation_config_type
      properties:
        name:
          type: string
          description: Name of the new annotation config
        space_id:
          type: string
          description: ID of the space the annotation config will belong to
        annotation_config_type:
          type: string
          enum:
            - FREEFORM
          description: Discriminator value identifying a freeform annotation config.
    ContinuousAnnotationConfig:
      type: object
      required:
        - id
        - name
        - created_at
        - space_id
        - type
        - minimum_score
        - maximum_score
      properties:
        id:
          type: string
          description: The unique identifier for the annotation config
        name:
          type: string
          description: The name of the annotation config
        created_at:
          type: string
          description: The timestamp for when the annotation config was created
          format: date-time
        space_id:
          type: string
          description: The space id the annotation config belongs to
        type:
          type: string
          enum:
            - CONTINUOUS
          description: Discriminator value identifying a continuous annotation config.
        minimum_score:
          type: number
          format: double
          description: The minimum score value
        maximum_score:
          type: number
          format: double
          description: The maximum score value
        optimization_direction:
          allOf:
            - $ref: '#/components/schemas/OptimizationDirection'
          description: >-
            Direction for optimization. When absent, the server treats the value
            as `NONE`.
    CategoricalAnnotationConfig:
      type: object
      required:
        - id
        - name
        - created_at
        - space_id
        - type
        - values
      properties:
        id:
          type: string
          description: The unique identifier for the annotation config
        name:
          type: string
          description: The name of the annotation config
        created_at:
          type: string
          description: The timestamp for when the annotation config was created
          format: date-time
        space_id:
          type: string
          description: The space id the annotation config belongs to
        type:
          type: string
          enum:
            - CATEGORICAL
          description: Discriminator value identifying a categorical annotation config.
        values:
          type: array
          description: An array of categorical annotation values
          items:
            $ref: '#/components/schemas/CategoricalAnnotationValue'
        optimization_direction:
          allOf:
            - $ref: '#/components/schemas/OptimizationDirection'
          description: >-
            Direction for optimization. When absent, the server treats the value
            as `NONE`.
    FreeformAnnotationConfig:
      type: object
      required:
        - id
        - name
        - created_at
        - space_id
        - type
      properties:
        id:
          type: string
          description: The unique identifier for the annotation config
        name:
          type: string
          description: The name of the annotation config
        created_at:
          type: string
          description: The timestamp for when the annotation config was created
          format: date-time
        space_id:
          type: string
          description: The space id the annotation config belongs to
        type:
          type: string
          enum:
            - FREEFORM
          description: Discriminator value identifying a freeform annotation config.
    OptimizationDirection:
      type: string
      enum:
        - MAXIMIZE
        - MINIMIZE
        - NONE
      default: NONE
      description: |
        The direction for optimization. Defaults to `NONE` when omitted.
        - MAXIMIZE: higher scores are better
        - MINIMIZE: lower scores are better
        - NONE: higher or lower scores are neither better nor worse
    CategoricalAnnotationValue:
      type: object
      required:
        - label
      properties:
        label:
          type: string
          description: The label value
        score:
          type: number
          format: double
          description: A score to associate with the label
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <api-key>
      description: >
        Most Arize AI endpoints require authentication. For those endpoints that
        require authentication, include your API key in the request header using
        the format

        ``` Authorization: Bearer <api-key>

        ```

````