---
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.
  - `as_of` string, date-time, nullable — ADM-15: return the judgment set AS IT STOOD at this instant — annotations created later are excluded, and each remaining annotation is reconstructed to its state at that time from its revision chain. This is the reproducible-evaluation handle: an evaluation pins its as_of and re-reads the identical set later.

## 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
    - `version` integer — Current version; starts at 1, bumps per edit.
    - `revisions` AnnotationRevision[] — Backward deltas preserving every superseded version.
      - `version` integer, required — The version number this revision PRESERVES (pre-edit).
      - `prior` object, required — Pre-edit values of the fields the superseding edit changed. Applying these onto the next-newer state reconstructs this version.
      - `edited_at` string, date-time, required — When the edit that superseded this version happened.
      - `edited_by` string, required — Actor who made the superseding edit (user or API key id).
      - `edited_by_type` string, required — Actor type of the superseding editor.
  - `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/revisions/27f74c951c4d/schema)