---
title: "List Annotations"
method: POST
path: "/v1/annotations/list"
tags: ["Annotations"]
---

# List Annotations

`POST /v1/annotations/list`

Query annotations with optional filters.

## Query parameters

- `skip` integer
- `limit` integer

## Request body

- ListAnnotationsRequest — Query parameters for listing annotations.
  - `document_id` string, nullable — Filter by document.
  - `collection_id` string, nullable — Filter by collection.
  - `label` string, nullable — Filter by label.
  - `actor_id` string, nullable — Filter by who annotated.
  - `retriever_id` string, nullable — Filter by retriever.

## Response `200`

Successful Response

- ListAnnotationsResponse — Paginated annotation list.
  - `results` AnnotationResponse[]
    - `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
  - `total_count` integer

## 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)