Skip to main content
POST
Create Annotation

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 | null

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 | null

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>