Create Annotation

curl --request POST \ --url https://api.mixpeek.com/v1/annotations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "document_id": "<string>", "label": "<string>", "collection_id": "<string>", "confidence": 0.5, "reasoning": "<string>", "payload": {}, "retriever_id": "<string>", "execution_id": "<string>", "stage_name": "<string>" } '

{ "document_id": "<string>", "namespace_id": "<string>", "label": "<string>", "annotation_id": "<string>", "collection_id": "<string>", "confidence": 0.5, "reasoning": "<string>", "payload": {}, "retriever_id": "<string>", "execution_id": "<string>", "stage_name": "<string>", "actor_id": "system", "actor_type": "system", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" }

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a new annotation on a document.

document_id

string

required

Document to annotate.

label

string

required

Decision label (e.g. 'approved', 'rejected', 'deferred').

Required string length: 1 - 100

collection_id

string | null

Collection the document belongs to.

confidence

number | null

Human confidence (0.0–1.0).

Required range: 0 <= x <= 1

reasoning

string | null

Why this decision was made.

Maximum string length: 5000

payload

Payload · object

Structured payload (use-case-specific).

retriever_id

string | null

execution_id

string | null

stage_name

string | null

Response

Successful Response

Single annotation response.

document_id

string

required

The document this annotation is attached to.

namespace_id

string

required

Namespace scope.

label

string

required

Human decision label. Domain-specific — e.g. 'approved', 'rejected', 'deferred', 'infringement', 'safe', 'confirmed_dupe'.

Required string length: 1 - 100

annotation_id

string

Unique annotation identifier.

collection_id

string | null

Collection the document belongs to.

confidence

number | null

Human confidence in this decision (0.0–1.0).

Required range: 0 <= x <= 1

reasoning

string | null

Why this decision was made. Stored for audit trail.

Maximum string length: 5000

payload

Payload · object

Use-case-specific structured data. E.g. {'codes_approved': ['E11.40'], 'raf_impact': 0.302}

retriever_id

string | null

Retriever that produced the document being annotated.

execution_id

string | null

Retriever execution ID.

stage_name

string | null

Stage that produced the result (e.g. 'llm_enrich').

actor_id

string

default:system

Who made the annotation (user ID or API key ID).

actor_type

string

default:system

Actor type: 'user', 'api_key', or 'system'.

created_at

string<date-time>

updated_at

string<date-time>