---
title: "Bulk Annotations"
method: POST
path: "/v1/annotations/bulk"
tags: ["Annotations"]
---

# Bulk Annotations

`POST /v1/annotations/bulk`

Create, update, and/or delete annotations in a single call.

Each operation is independent — a failure in one does not roll back the others.
Maximum 1000 operations per type (creates, updates, deletes).

## Request body

- BulkAnnotationsRequest — Bulk create, update, and/or delete annotations in a single call. Provide any combination of creates, updates, and deletes. Each operation is independent — a failure in one does not roll back the others.
  - `create` BulkAnnotationCreate[] — Annotations to create.
    - `document_id` string, required — Document to annotate.
    - `collection_id` string, nullable
    - `label` string, required
    - `confidence` number, nullable
    - `reasoning` string, nullable
    - `payload` object, nullable
    - `retriever_id` string, nullable
    - `execution_id` string, nullable
    - `stage_name` string, nullable
  - `update` BulkAnnotationUpdate[] — Annotations to update.
    - `annotation_id` string, required — Annotation to update.
    - `label` string, nullable
    - `confidence` number, nullable
    - `reasoning` string, nullable
    - `payload` object, nullable
  - `delete` string[] — Annotation IDs to delete.

## Response `200`

Successful Response

- BulkAnnotationsResponse — Response for bulk annotation operations.
  - `created_count` integer
  - `updated_count` integer
  - `deleted_count` integer
  - `failed_count` integer
  - `results` BulkAnnotationResult[]
    - `annotation_id` string, nullable — Annotation ID (set for create/update).
    - `operation` string, required — Operation type: create, update, or delete.
    - `success` boolean, required — Whether the operation succeeded.
    - `error` string, nullable — Error message if failed.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)