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
paths:
  /v2/datasets:
    get:
      tags:
        - Datasets
      operationId: datasets_list
      x-stability: beta
      summary: List datasets
      description: "List datasets the user has access to. The datasets are sorted by creation date,\nwith the most recently-created datasets coming first. The dataset versions\nare not included in this response. To get the versions of a specific dataset,\nuse the Get Dataset by ID endpoint.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/SpaceIdQueryParam"
        - $ref: "#/components/parameters/LimitQueryParamMax500"
        - $ref: "#/components/parameters/CursorQueryParam"
      responses:
        "200":
          $ref: "#/components/responses/DatasetList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
    post:
      tags:
        - Datasets
      operationId: datasets_create
      x-stability: beta
      summary: Create a new dataset
      description: "Create a new dataset with JSON examples. Empty datasets are not allowed.\nDataset names must be unique within a given space.\n\n**Example payload**\n- Each item in `examples[]` may contain **any user-defined fields**.\n- **Do not** include system-managed fields on input: `id`, `created_at`, `updated_at`.\n  Requests that contain these fields in any example **will be rejected**.\n- Each example **must contain at least one property** (i.e., `{}` is invalid).\n\n**Valid example** (create)\n```json\n{\n  \"name\": \"my-dataset\",\n  \"spaceId\": \"spc_123\",\n  \"examples\": [\n    { \"question\": \"What is 2+2?\", \"answer\": \"4\", \"topic\": \"math\" }\n  ]\n}\n```\n\n**Invalid example** (contains system fields)\n```json\n{\n  \"name\": \"my-dataset\",\n  \"spaceId\": \"spc_123\",\n  \"examples\": [\n    { \"id\": \"ex_1\", \"input\": \"Hello\" }   // \u274C 'id' not allowed on create\n  ]\n}\n```\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      requestBody:
        $ref: "#/components/requestBodies/CreateDatasetRequestBody"
      responses:
        "201":
          $ref: "#/components/responses/Dataset"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /v2/datasets/{datasetId}:
    get:
      tags:
        - Datasets
      operationId: datasets_get
      x-stability: beta
      summary: Get a dataset
      description: "Get a dataset object by its ID. This includes the dataset's versions,\nsorted by creation date, with the most recently-created version first.\nThis endpoint does not include the dataset's examples. To get the examples\nof a specific dataset version, use the List Examples for a Dataset endpoint.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/DatasetIdPathParam"
        - $ref: "#/components/parameters/DatasetVersionIdQueryParam"
      responses:
        "200":
          $ref: "#/components/responses/Dataset"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
    delete:
      tags:
        - Datasets
      operationId: datasets_delete
      x-stability: beta
      summary: Delete a dataset
      description: "Delete a dataset by its ID. This operation is irreversible.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/DatasetIdPathParam"
      responses:
        "204":
          $ref: "#/components/responses/DatasetDeleted"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
  /v2/datasets/{datasetId}/examples:
    get:
      tags:
        - Datasets
      operationId: datasets_examples_list
      x-stability: beta
      summary: List dataset examples
      description: "List examples for a given dataset and version. If version is not passed,\nthe latest version is selected. Examples are sorted by insertion order.\n\n**Pagination**\n- Response includes `pagination` for forward compatibility.\n- **Currently not implemented**: `pagination.hasMore` is always `false` and `pagination.nextCursor` is omitted.\n- When pagination is enabled in the future, the behavior will match other list endpoints (cursor-based, opaque tokens).\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/DatasetIdPathParam"
        - $ref: "#/components/parameters/DatasetVersionIdQueryParam"
        - $ref: "#/components/parameters/LimitQueryParamMax10k"
      responses:
        "200":
          $ref: "#/components/responses/DatasetExampleList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
    post:
      tags:
        - Datasets
      operationId: datasets_examples_insert
      x-stability: beta
      summary: Add new examples to a dataset
      description: "Appends new examples to an existing dataset and a particular version.\nIf the version is not passed, the latest version is selected.\nThe inserted examples will be assigned autogenerated, unique IDs.\n\n**Example payload**\n- Each item in `examples[]` may contain **any user-defined fields**.\n- **Do not** include system-managed fields on input: `id`, `created_at`, `updated_at`.\n  Requests that contain these fields in any example **will be rejected**.\n- Each example **must contain at least one property** (i.e., `{}` is invalid).\n\n**Valid example** (create)\n```json\n{\n  \"examples\": [\n    { \"question\": \"What is 2+2?\", \"answer\": \"4\", \"topic\": \"math\" }\n  ]\n}\n```\n\n**Invalid example** (contains system fields)\n```json\n{\n  \"examples\": [\n    { \"id\": \"ex_1\", \"input\": \"Hello\" }   // \u274C 'id' not allowed on create\n  ]\n}\n```\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/DatasetIdPathParam"
        - $ref: "#/components/parameters/DatasetVersionIdQueryParam"
      requestBody:
        $ref: "#/components/requestBodies/InsertDatasetExamplesRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/Dataset"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
    patch:
      tags:
        - Datasets
      operationId: datasets_examples_update
      x-stability: beta
      summary: Update existing examples in a dataset
      description: "Updates existing dataset examples by matching their 'id' field. If the 'id'\nfield is not passed in the examples data, they will be rejected.\n\nIf an example ID does not match any existing example in the dataset version,\nit will be ignored. In other words, only examples with IDs that already exist\nwill be updated. To add new examples, use the Insert Dataset Examples endpoint.\n\nAdding columns that do not exist in the dataset schema is allowed, but removing\nexisting columns is not.\n\nOptionally, the update can create a new version of the dataset. In this case,\nthe outcome of the update will be reflected only in the new version, while the\nprevious version remains unchanged. If a new version is not created, the updates\nwill be applied directly (in place) to the specified version.\n\n**Example payload**\n- Each item in `examples[]` may contain **any user-defined fields**.\n- Each item in `examples[]` must include the `id` field to identify the example to update.\n- **Do not** include system-managed fields on input: `created_at`, `updated_at`.\n  Requests that contain these fields in any example **will be rejected**.\n- Each example **must contain at least one property** (i.e., `{}` is invalid).\n\n**Valid example** (create)\n```json\n{\n  \"examples\": [\n    { \"id\": \"ex_001\", \"question\": \"What is 2+2?\", \"answer\": \"4\", \"topic\": \"math\" }\n  ]\n}\n```\n\n**Invalid example** (contains system fields)\n```json\n{\n  \"examples\": [\n    { \"input\": \"Hello\" }   // \u274C 'id' not specified for update\n  ]\n}\n```\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/DatasetIdPathParam"
        - $ref: "#/components/parameters/DatasetVersionIdQueryParam"
      requestBody:
        $ref: "#/components/requestBodies/UpdateDatasetExamplesRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/Dataset"
        "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/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
  /v2/experiments:
    get:
      tags:
        - Experiments
      operationId: experiments_list
      x-stability: beta
      summary: List experiments
      description: "List all experiments a user has access to. To filter experiments by the dataset they were run on,\nprovide the `datasetId` query parameter.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/DatasetIdQueryParam"
        - $ref: "#/components/parameters/LimitQueryParamMax500"
        - $ref: "#/components/parameters/CursorQueryParam"
      responses:
        "200":
          $ref: "#/components/responses/ExperimentList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
    post:
      tags:
        - Experiments
      operationId: experiments_create
      x-stability: beta
      summary: Create a new experiment
      description: "Create a new experiment with a list of JSON objects (or runs). Empty experiments are not allowed.\nEach run (JSON object) must include an `example_id` field that corresponds to an example in the dataset,\nand a `output` field that contains the task's output for the example (the input).\n\nThe name of the experiment must be unique within a given dataset.\n\nBody containing experiment creation parameters.\n\n**Rules**\n- `name` must be **unique within the target dataset**.\n- Provide at least **one** run in `experimentRuns`.\n- Each run **must** include:\n  - `example_id` \u2014 the ID of an existing example in the dataset/version\n  - `output` \u2014 the model/task output for that example\n- You may include **any additional fields** per run (e.g., `model`, `latency_ms`,\n  `temperature`, `prompt`, `tool_calls`, etc.). These are stored and can be used\n  for analysis/filters.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      requestBody:
        $ref: "#/components/requestBodies/CreateExperimentRequestBody"
      responses:
        "201":
          $ref: "#/components/responses/Experiment"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
  /v2/experiments/{experimentId}:
    get:
      tags:
        - Experiments
      operationId: experiments_get
      x-stability: beta
      summary: Get an experiment
      description: "Get an experiment object by its ID. This includes does not include the experiment's runs.\nTo get the runs of a specific experiment, use the List Experiment Runs endpoint.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/ExperimentIdPathParam"
      responses:
        "200":
          $ref: "#/components/responses/Experiment"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
    delete:
      tags:
        - Experiments
      operationId: experiments_delete
      x-stability: beta
      summary: Delete an experiment by ID
      description: "Delete an experiment by its ID. This operation is irreversible.\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/ExperimentIdPathParam"
      responses:
        "204":
          $ref: "#/components/responses/ExperimentDeleted"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
  /v2/experiments/{experimentId}/runs:
    get:
      tags:
        - Experiments
      operationId: experiments_runs_list
      x-stability: beta
      summary: List experiment runs
      description: "List runs for a given experiment. The runs are sorted by insertion order.\n\n**Pagination**\n- Response includes `pagination` for forward compatibility.\n- **Currently not implemented**: `pagination.hasMore` is always `false` and `pagination.nextCursor` is omitted.\n- When pagination is enabled in the future, the behavior will match other list endpoints (cursor-based, opaque tokens).\n\n\u26A0\uFE0F **Beta Warning:** This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).\n"
      parameters:
        - $ref: "#/components/parameters/ExperimentIdPathParam"
        - $ref: "#/components/parameters/LimitQueryParamMax10k"
      responses:
        "200":
          $ref: "#/components/responses/ExperimentRunsList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
components:
  schemas:
    PrimitiveValue:
      description: A JSON primitive value (string, number, integer, or boolean)
      oneOf:
        - $ref: "#/components/schemas/PrimitiveValueInteger"
        - $ref: "#/components/schemas/PrimitiveValueNumber"
        - $ref: "#/components/schemas/PrimitiveValueString"
        - $ref: "#/components/schemas/PrimitiveValueBoolean"
    PrimitiveValueInteger:
      type: integer
    PrimitiveValueNumber:
      type: number
      format: double
    PrimitiveValueString:
      type: string
    PrimitiveValueBoolean:
      type: boolean
    Dataset:
      required:
        - id
        - name
        - spaceId
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the dataset
        name:
          type: string
          description: Name of the dataset
        spaceId:
          type: string
          description: Unique identifier for the space this dataset belongs to
        createdAt:
          type: string
          description: Timestamp for when the dataset was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp for the last update of the dataset
          format: date-time
        versions:
          type: array
          items:
            $ref: "#/components/schemas/DatasetVersion"
          description: List of versions associated with this dataset
      description:
        "A dataset is a structured collection of examples used to test and evaluate

        LLM applications. Datasets allow you to test models consistently across

        any real-world scenarios and edge cases, quickly identify regressions,

        and track measurable improvements.

        "
      additionalProperties: false
    DatasetVersion:
      required:
        - id
        - name
        - datasetId
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the dataset version
        name:
          type: string
          description: Name of the dataset version
        datasetId:
          type: string
          description: Unique identifier for the dataset this version belongs to
        createdAt:
          type: string
          description: Timestamp for when the dataset version was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp for the last update of the dataset version
          format: date-time
      description:
        "A dataset version is a saved snapshot of a dataset. Arize stores datasets

        as version-controlled collections of examples for experiments.

        When you update a dataset, you can do so inplace  or create a new version

        while preserving access to previous versions.

        "
      additionalProperties: false
    Experiment:
      required:
        - id
        - name
        - datasetId
        - datasetVersionId
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the experiment
        name:
          type: string
          description: Name of the experiment
        datasetId:
          type: string
          description: Unique identifier for the dataset this experiment belongs to
        datasetVersionId:
          type: string
          description: Unique identifier for the dataset version this experiment belongs to
        createdAt:
          type: string
          description: Timestamp for when the experiment was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp for the last update of the experiment
          format: date-time
        experimentTracesProjectId:
          type: string
          description: Unique identifier for the experiment traces project this experiment belongs to (if it exists)
      description:
        "Experiments combine a dataset (example inputs/expected outputs), a task

        (the function that produces model outputs), and one or more evaluators

        (code or LLM judges) to measure performance. Each run is stored independently

        so you can compare runs, track progress, and validate improvements over time.

        See the full definition on the Experiments page.


        Use an experiment to run tasks on a dataset, attach evaluators to score outputs,

        and compare runs to confirm improvements.

        "
      additionalProperties: false
    PaginationMetadata:
      required:
        - hasMore
      type: object
      properties:
        nextCursor:
          type: string
          description:
            "Opaque cursor for fetching the next page. Treat as an unreadable token. Present when `hasMore` is true; omitted when `hasMore` is false.

            "
        hasMore:
          type: boolean
          description: True if another page of results is available.
      description:
        "Cursor-based pagination metadata. Use `nextCursor` in the subsequent request's `cursor` query parameter.

        "
      additionalProperties: false
    DatasetExampleCreate:
      type: object
      description:
        "A dataset example with arbitrary user-defined fields. System-managed fields are excluded for creation requests.

        "
      additionalProperties:
        description: Additional user-defined fields in the dataset example
        $ref: "#/components/schemas/PrimitiveValue"
    DatasetExampleUpdate:
      type: object
      description:
        "A dataset example with arbitrary user-defined fields. System-managed fields, except 'id', are excluded for update requests.

        "
      properties:
        id:
          type: string
          description: System-assigned unique ID for the example
      required:
        - id
      additionalProperties:
        description: Additional user-defined fields in the dataset example
        $ref: "#/components/schemas/PrimitiveValue"
    DatasetExample:
      type: object
      description:
        "A dataset example with arbitrary user-defined fields. System-managed fields are included as read-only for responses.

        "
      properties:
        id:
          type: string
          description: System-assigned unique ID for the example
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp for when the example was created
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: Timestamp for the last update of the example
          readOnly: true
      required:
        - id
        - createdAt
        - updatedAt
      additionalProperties:
        description: Additional user-defined fields in the dataset example
        $ref: "#/components/schemas/PrimitiveValue"
    ExperimentRunCreate:
      type: object
      description: An experiment run with experiment data including outputs, evaluations, and trace metadata
      properties:
        exampleId:
          type: string
          description: ID of the dataset example associated with this experiment run
        output:
          type: string
          description: output of the task for the matching example
      required:
        - exampleId
        - output
      additionalProperties:
        description: Additional user-defined fields in the experiment run
        $ref: "#/components/schemas/PrimitiveValue"
    ExperimentRun:
      type: object
      description: An experiment run with experiment data including outputs, evaluations, and trace metadata
      properties:
        id:
          type: string
          description: System-assigned unique ID for the example
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp for when the experiment was run
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: Timestamp for the last update of the experiment run
          readOnly: true
        exampleId:
          type: string
          description: ID of the dataset example associated with this experiment run
          readOnly: true
        output:
          type: string
          description: output of the task for the matching example
      required:
        - id
        - createdAt
        - updatedAt
        - exampleId
        - output
      additionalProperties:
        description: Additional user-defined fields in the experiment run
        $ref: "#/components/schemas/PrimitiveValue"
    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
          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
          description: A URI reference that identifies the specific occurrence of the problem
      required:
        - title
        - status
      additionalProperties: false
    Id:
      type: string
      description: A universally unique identifier
  responses:
    Dataset:
      description: A dataset object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Dataset"
    DatasetList:
      description: Returns a list of dataset objects
      content:
        application/json:
          schema:
            type: object
            required:
              - datasets
              - pagination
            properties:
              datasets:
                type: array
                items:
                  $ref: "#/components/schemas/Dataset"
                description: A list of datasets
              pagination:
                $ref: "#/components/schemas/PaginationMetadata"
                description: Pagination metadata for cursor-based navigation
            additionalProperties: false
    DatasetDeleted:
      description: Dataset successfully deleted
    DatasetExampleList:
      description: Returns a list of dataset examples as structured objects
      content:
        application/json:
          schema:
            type: object
            properties:
              examples:
                type: array
                description: Array of example objects from the dataset
                items:
                  $ref: "#/components/schemas/DatasetExample"
              pagination:
                $ref: "#/components/schemas/PaginationMetadata"
                description: Pagination metadata for cursor-based navigation
            required:
              - examples
              - pagination
            additionalProperties: false
          example:
            examples:
              - question: What is 2 + 2?
                answer: 4
                topic: arithmetic
                isCorrect: true
              - question: What is the square root of 16?
                answer: 4
                topic: geometry
                isCorrect: true
              - question: If 3x = 12, what is x?
                answer: 3
                topic: algebra
                isCorrect: false
            pagination:
              nextCursor: cursor_12345
              hasMore: true
    Experiment:
      description: An experiment object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Experiment"
    ExperimentList:
      description: Returns a list of experiment objects
      content:
        application/json:
          schema:
            type: object
            required:
              - experiments
              - pagination
            properties:
              experiments:
                type: array
                items:
                  $ref: "#/components/schemas/Experiment"
                description: A list of experiments
              pagination:
                $ref: "#/components/schemas/PaginationMetadata"
                description: Pagination metadata for cursor-based navigation
            additionalProperties: false
    ExperimentDeleted:
      description: Experiment successfully deleted
    ExperimentRunsList:
      description: Returns a list of experiment run objects
      content:
        application/json:
          schema:
            type: object
            required:
              - experimentRuns
              - pagination
            properties:
              experimentRuns:
                type: array
                items:
                  $ref: "#/components/schemas/ExperimentRun"
                description: Array of experiment run objects containing experiment fields and evaluations
              pagination:
                $ref: "#/components/schemas/PaginationMetadata"
                description: Pagination metadata for cursor-based navigation
            additionalProperties: false
    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://example.com/probs/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://example.com/probs/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://example.com/probs/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://example.com/probs/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://example.com/probs/resource-conflict
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      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://example.com/probs/rate-limit-exceeded
  parameters:
    DatasetIdPathParam:
      name: datasetId
      in: path
      description: The unique identifier of the dataset
      required: true
      schema:
        $ref: "#/components/schemas/Id"
    ExperimentIdPathParam:
      name: experimentId
      in: path
      description: The unique identifier of the experiment
      required: true
      schema:
        $ref: "#/components/schemas/Id"
    SpaceIdQueryParam:
      name: spaceId
      in: query
      description: Filter search results to a particular space ID
      schema:
        $ref: "#/components/schemas/Id"
    DatasetIdQueryParam:
      name: datasetId
      in: query
      description: Filter experiments to a particular dataset ID
      schema:
        $ref: "#/components/schemas/Id"
    DatasetVersionIdQueryParam:
      name: datasetVersionId
      in: query
      description: The unique identifier of the dataset version
      schema:
        $ref: "#/components/schemas/Id"
    LimitQueryParamMax500:
      name: limit
      in: query
      description: Maximum items to return
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    LimitQueryParamMax10k:
      name: limit
      in: query
      description: Maximum items to return
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 50
    CursorQueryParam:
      name: cursor
      in: query
      description:
        "Opaque pagination cursor returned from a previous response (`pagination.nextCursor`). Treat it as an unreadable token; do not attempt to parse or construct it.

        "
      schema:
        type: string
  requestBodies:
    CreateDatasetRequestBody:
      description: Body containing dataset creation parameters
      required: true
      content:
        application/json:
          schema:
            required:
              - name
              - spaceId
              - examples
            type: object
            properties:
              name:
                type: string
              spaceId:
                type: string
              examples:
                type: array
                description: Array of examples for the new dataset
                items:
                  $ref: "#/components/schemas/DatasetExampleCreate"
          example:
            name: Math Questions Dataset
            spaceId: space_12345
            examples:
              - question: What is 2 + 2?
                answer: "4"
                topic: arithmetic
              - question: What is the square root of 16?
                answer: "4"
                topic: geometry
              - question: If 3x = 12, what is x?
                answer: "4"
                topic: algebra
    InsertDatasetExamplesRequestBody:
      description: Body containing dataset examples for insert (append) operation with auto-generated IDs
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              examples:
                type: array
                description: Array of examples to append to the dataset version
                items:
                  $ref: "#/components/schemas/DatasetExampleCreate"
            required:
              - examples
            additionalProperties: false
          example:
            examples:
              - question: What is 2 + 2?
                answer: "4"
                topic: arithmetic
              - question: What is the square root of 16?
                answer: "4"
                topic: geometry
              - question: If 3x = 12, what is x?
                answer: "4"
                topic: algebra
    UpdateDatasetExamplesRequestBody:
      description: Body containing dataset examples for update operation by ID matching
      required: true
      content:
        application/json:
          schema:
            required:
              - examples
            type: object
            properties:
              examples:
                type: array
                description: Array of examples with 'id' field for matching and updating existing records
                items:
                  $ref: "#/components/schemas/DatasetExampleUpdate"
              newVersion:
                # TODO(Kiko): Should new version be a query parameter?
                type: string
                description:
                  "Name for the new version. If provided (non-empty), creates a new version with that name.

                  If omitted or empty, updates the existing version in-place.

                  "
          example:
            examples:
              - id: example_001
                question: What is 2 * 2?
              - id: example_002
                question: What is the square root of 64?
                answer: "8"
              - id: example_003
                question: If 9x = 36, what is x?
                topic: algebra
    CreateExperimentRequestBody:
      description: Body containing experiment creation parameters
      required: true
      content:
        application/json:
          schema:
            required:
              - name
              - datasetId
              - experimentRuns
            type: object
            properties:
              name:
                type: string
                description: Name of the experiment
              datasetId:
                type: string
                description: ID of the dataset to create the experiment for
              experimentRuns:
                type: array
                description: Array of experiment run data
                items:
                  $ref: "#/components/schemas/ExperimentRunCreate"
          example:
            name: My Experiment Name
            datasetId: dataset_12345
            experimentRuns:
              - example_id: example_001
                output: "4"
                model: gpt-4o-mini
                temperature: 0.2
                latency_ms: 118
                prompt: Answer the math question briefly.
              - example_id: example_002
                output: "4"
                model: gpt-4o-mini
                temperature: 0.2
                latency_ms: 132
              - example_id: example_003
                output: "4"
                model: gpt-4o-mini
                temperature: 0.2
                latency_ms: 125
  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
  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>

        ```

        "
security:
  - bearerAuth: []
tags:
  - name: Datasets
    description: Datasets are structured, version-controlled example collections you use to run, evaluate, and track LLM experiments.
  - name: Experiments
    description: Experiments let you systematically test prompt/model changes using datasets, tasks, and evaluators.
servers:
  - description: Global
    url: https://api.arize.com
  - description: Regional
    url: https://api.{region}.arize.com
    variables:
      region:
        default: us-central-1a
        enum:
          - ca-central-1a
          - eu-west-1a
          - us-central-1a
          - us-east-1b
  - description: Custom Host
    url: https://{host}
    variables:
      host:
        default: api.arize.com
