> This page is for version v2026-02-09 (default).
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# Create Evaluation Set Items

POST https://api.extend.ai/evaluation_sets/{evaluationSetId}/items
Content-Type: application/json

Evaluation set items are the individual files and expected outputs that are used to evaluate the performance of a given extractor, classifier, or splitter in Extend. This endpoint will create new evaluation set items in Extend, which will be used during an evaluation run.

Each item references exactly one of:

- **`fileId`** — a single file. The item is evaluated as one single-file run.
- **`fileIds`** — an ordered package of 2–50 files. The item is evaluated as one [multifile extraction](https://docs.extend.ai/2026-02-09/extraction/multifile) run, with a single `expectedOutput` covering the whole package. Multifile items are only supported on evaluation sets attached to a JSON-schema extractor.

**Limit:** You can create up to 100 items at a time.

Learn more about how to create evaluation set items in the [Evaluation Sets](https://docs.extend.ai/2026-02-09/evaluation/overview) product page.


Reference: https://docs.extend.ai/api-reference/endpoints/evaluation/create-evaluation-set-item

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.extend.ai` (Production, default)
- `https://api.us2.extend.app` (Production US2)
- `https://api.eu1.extend.ai` (Production EU1)

## Request

### Path parameters

- `evaluationSetId` (string, required) — The ID of the evaluation set. Example: `"ev_2LcgeY_mp2T5yPaEuq5Lw"`

### Headers

- `x-extend-api-version` ("2026-02-09", optional, default: 2026-02-09) — API version to use for the request. If you're using an SDK, you can ignore this parameter. If you are not using an SDK and do not specify a version, you will either receive a `400 Bad Request` or be set to a previous legacy version. See [API Versioning](https://docs.extend.ai/2026-02-09/api-reference/api-versioning) for more details.
- `x-extend-workspace-id` (string, optional) — The workspace ID to target. **Required** when using an organization-scoped API key; optional for workspace-scoped keys (the key is already tied to a workspace). See [Authentication](https://docs.extend.ai/2026-02-09/api-reference/authentication) for details on API key scopes.

### Body (application/json)

This endpoint expects an object.

- `items` (list of EvaluationSetsEvaluationSetIdItemsPostRequestBodyContentApplicationJsonSchemaItemsItems, required) — An array of objects representing the evaluation set items to create.

## Response

### 200

Evaluation set items created successfully

- `evaluationSetItems` (list of EvaluationSetItem, required)

## Errors

### 400 Bad Request Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 401 Unauthorized Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 402 Payment Required Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 403 Forbidden Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 404 Not Found Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 422 Unprocessable Entity Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 429 Too Many Requests Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 500 Internal Server Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

## Types

### EvaluationSetsEvaluationSetIdItemsPostRequestBodyContentApplicationJsonSchemaItemsItems

Each item references exactly one of `fileId` (a single file) or `fileIds` (a multifile item) — provide one or the other.

- `expectedOutput` (ProvidedProcessorOutput, required) — The expected output that will be compared to the actual output of the extractor, classifier, or splitter when run against the file(s).
- `fileId` (string, optional) — Extend's internal ID for the file. It will always start with "file_". Mutually exclusive with `fileIds`. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`
- `fileIds` (list of string, optional) — An ordered list of Extend file IDs to evaluate together as a single multifile item. Mutually exclusive with `fileId`. Each evaluation run evaluates the item as one multifile extraction run over these files, in this order. Only supported for evaluation sets whose entity is a JSON-schema extractor. File IDs must be unique. See [Multifile Extraction](https://docs.extend.ai/2026-02-09/extraction/multifile) for details.

### EvaluationSetItem

- `object` (enum, required) — The type of object. In this case, it will always be `"evaluation_set_item"`.
  - Allowed values: `evaluation_set_item`
- `id` (string, required) — The ID of the evaluation set item. Example: `"evi_kR9mNP12Qw4yTv8BdR3H"`
- `evaluationSetId` (string, required) — The ID of the evaluation set that this item belongs to. Example: `"ev_2LcgeY_mp2T5yPaEuq5Lw"`
- `file` (FileSummary, required, nullable) — A summary of the file associated with the evaluation set item. `null` for multifile items (use `files` instead).
- `files` (list of FileSummary, required, nullable) — The files associated with a multifile evaluation set item, in the order they were submitted. Only populated for items created with `fileIds`. For single-file items, this is `null` — use `file` instead.
- `expectedOutput` (ProvidedProcessorOutput, required) — The expected output that will be used to evaluate the performance of the extractor, classifier, or splitter associated with the evaluation set. This must conform to the output schema of the entity associated with the evaluation set.
- `createdBy` (CreatedBy, required) — The actor that created this resource. * `user` — the resource was created via the studio by a logged-in user. The user's `email` is exposed. * `api_key` — the resource was created via the API using an API key. The key's `name` is exposed. May be `null` for resources created before attribution.

### ProvidedProcessorOutput

### FileSummary

- `object` (enum, required) — The type of object. Will always be `"file"`.
  - Allowed values: `file`
- `id` (string, required) — ID for the file. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`
- `name` (string, required) — The name of the file Example: `"Invoices.pdf"`
- `type` (enum, required, nullable) — The type of the file. **Availability:** Present when the file type could be determined.
  - Allowed values: `PDF`, `CSV`, `IMG`, `TXT`, `DOCX`, `EXCEL`, `XML`, `HTML`
- `parentFileId` (string, required, nullable) — ID of the parent file. **Availability:** Present for files created via a Splitter in a workflow.
- `metadata` (FileMetadata, required)
- `createdAt` (string, required) — The time (in UTC) at which the object was created. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`
- `updatedAt` (string, required) — The time (in UTC) at which the object was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`

### CreatedBy

The actor that created this resource. * `user` — the resource was created via the studio by a logged-in user. The user's `email` is exposed. * `api_key` — the resource was created via the API using an API key. The key's `name` is exposed. May be `null` for resources created before attribution.

- `type`: `user` (user)
  - `email` (string, required) — The email address of the user who created the resource.
- `type`: `api_key` (api_key)
  - `name` (string, required) — The name of the API key that created the resource.

### ProvidedExtractOutput

The expected extraction output. **Important:** Make sure to nest the JSON object conforming to the schema in a `value` object, and include all properties defined in the schema.

- `value` (map from string to any, optional) — The expected extraction output, provided as a JSON object that conforms to the schema defined in the extractor config

### ProvidedClassifyOutput

- `id` (string, required) — The unique identifier for this classification (defined in the classifier config)
- `type` (string, required) — The type of classification (defined in the classifier config)

### ProvidedSplitOutput

- `splits` (list of ProvidedSplitOutputSplitsItems, required)

### FileMetadata

- `pageCount` (double, optional) — The number of pages in the file. This is only set for PDF/DOCX files.
- `parentSplit` (ParentSplit, optional) — The split metadata details for a derivative file. **Availability:** Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

### ProvidedSplitOutputSplitsItems

- `classificationId` (string, required) — ID of the classification type (defined in the splitter config)
- `type` (string, required) — The type of the split document (defined in the splitter config), corresponds to the classificationId
- `startPage` (integer, required) — The start page of the split document
- `endPage` (integer, required) — The end page of the split document

### ParentSplit

The split metadata details for a derivative file. **Availability:** Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

- `id` (string, required) — The ID of the split.
- `type` (string, required) — The type of the split.
- `identifier` (string, required) — The identifier of the split.
- `startPage` (integer, required) — The start page of the split.
- `endPage` (integer, required) — The end page of the split.

## Examples

### Add a multifile item evaluated as one extraction run

**Request**

```json
{
  "items": [
    {
      "expectedOutput": {
        "value": {
          "vendor_name": "Acme Corp",
          "invoice_number": "INV-001",
          "total_amount": 1500
        },
        "type": "extraction"
      },
      "fileIds": [
        "file_xK9mLPqRtN3vS8wF5hB2cQ",
        "file_aB3cD4eF5gH6iJ7kL8mN9o"
      ]
    }
  ]
}
```

**Response**

```json
{
  "evaluationSetItems": [
    {
      "object": "evaluation_set_item",
      "id": "evi_kR9mNP12Qw4yTv8BdR3H",
      "evaluationSetId": "ev_2LcgeY_mp2T5yPaEuq5Lw",
      "file": {
        "object": "file",
        "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
        "name": "Invoices.pdf",
        "type": "PDF",
        "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
        "metadata": {
          "pageCount": 30,
          "parentSplit": {
            "id": "string",
            "type": "Invoice",
            "identifier": "other_2_9",
            "startPage": 1,
            "endPage": 10
          }
        },
        "createdAt": "2024-03-21T16:45:00Z",
        "updatedAt": "2024-03-21T16:45:00Z"
      },
      "files": [
        {
          "object": "file",
          "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
          "name": "Invoices.pdf",
          "type": "PDF",
          "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
          "metadata": {
            "pageCount": 30,
            "parentSplit": {
              "id": "string",
              "type": "Invoice",
              "identifier": "other_2_9",
              "startPage": 1,
              "endPage": 10
            }
          },
          "createdAt": "2024-03-21T16:45:00Z",
          "updatedAt": "2024-03-21T16:45:00Z"
        }
      ],
      "expectedOutput": {
        "value": {}
      },
      "createdBy": {
        "type": "user",
        "email": "matt@extend.app"
      }
    }
  ]
}
```

### Example 2

**Request**

```json
{
  "items": [
    {
      "expectedOutput": {
        "value": {
          "vendor_name": "Acme Corp",
          "invoice_number": "INV-001",
          "total_amount": 1500
        },
        "type": "extraction"
      },
      "fileId": "file_xK9mLPqRtN3vS8wF5hB2cQ"
    }
  ]
}
```

**Response**

```json
{
  "evaluationSetItems": [
    {
      "object": "evaluation_set_item",
      "id": "evi_kR9mNP12Qw4yTv8BdR3H",
      "evaluationSetId": "ev_2LcgeY_mp2T5yPaEuq5Lw",
      "file": {
        "object": "file",
        "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
        "name": "Invoices.pdf",
        "type": "PDF",
        "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
        "metadata": {
          "pageCount": 30,
          "parentSplit": {
            "id": "string",
            "type": "Invoice",
            "identifier": "other_2_9",
            "startPage": 1,
            "endPage": 10
          }
        },
        "createdAt": "2024-03-21T16:45:00Z",
        "updatedAt": "2024-03-21T16:45:00Z"
      },
      "files": [
        {
          "object": "file",
          "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
          "name": "Invoices.pdf",
          "type": "PDF",
          "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
          "metadata": {
            "pageCount": 30,
            "parentSplit": {
              "id": "string",
              "type": "Invoice",
              "identifier": "other_2_9",
              "startPage": 1,
              "endPage": 10
            }
          },
          "createdAt": "2024-03-21T16:45:00Z",
          "updatedAt": "2024-03-21T16:45:00Z"
        }
      ],
      "expectedOutput": {
        "value": {}
      },
      "createdBy": {
        "type": "user",
        "email": "matt@extend.app"
      }
    }
  ]
}
```