---
title: "Create Annotation"
method: POST
path: "/v1/annotations"
tags: ["Annotations"]
---

# Create Annotation

`POST /v1/annotations`

Record a human decision on a document.

## Request body

- CreateAnnotationRequest — Create a new annotation on a document.
  - `document_id` string, required — Document to annotate.
  - `collection_id` string, nullable — Collection the document belongs to.
  - `label` string, required — Decision label (e.g. 'approved', 'rejected', 'deferred').
  - `confidence` number, nullable — Human confidence (0.0–1.0).
  - `reasoning` string, nullable — Why this decision was made.
  - `payload` object, nullable — Structured payload (use-case-specific).
  - `retriever_id` string, nullable
  - `execution_id` string, nullable
  - `stage_name` string, nullable

## Response `200`

Successful Response

- AnnotationResponse — Single annotation response.
  - `annotation_id` string — Unique annotation identifier.
  - `document_id` string, required — The document this annotation is attached to.
  - `collection_id` string, nullable — Collection the document belongs to.
  - `namespace_id` string, required — Namespace scope.
  - `label` string, required — Human decision label. Domain-specific — e.g. 'approved', 'rejected', 'deferred', 'infringement', 'safe', 'confirmed_dupe'.
  - `confidence` number, nullable — Human confidence in this decision (0.0–1.0).
  - `reasoning` string, nullable — Why this decision was made. Stored for audit trail.
  - `payload` object, nullable — Use-case-specific structured data. E.g. {'codes_approved': ['E11.40'], 'raf_impact': 0.302}
  - `retriever_id` string, nullable — Retriever that produced the document being annotated.
  - `execution_id` string, nullable — Retriever execution ID.
  - `stage_name` string, nullable — Stage that produced the result (e.g. 'llm_enrich').
  - `actor_id` string — Who made the annotation (user ID or API key ID).
  - `actor_type` string — Actor type: 'user', 'api_key', or 'system'.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## 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/5d4c905106b4/schema)