v5

OpenAPI 3.1.02026-08-025631,1012.8 MB

Annotations

Create Annotation

Record a human decision on a document.

post/v1/annotations

Request body

document_idstring required

Document to annotate.

collection_idstring nullable

Collection the document belongs to.

labelstring required

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

confidencenumber nullable

Human confidence (0.0–1.0).

reasoningstring nullable

Why this decision was made.

payloadobject nullable

Structured payload (use-case-specific).

retriever_idstring nullable

execution_idstring nullable

stage_namestring nullable

Response

Successful Response

annotation_idstring

Unique annotation identifier.

document_idstring required

The document this annotation is attached to.

collection_idstring nullable

Collection the document belongs to.

namespace_idstring required

Namespace scope.

labelstring required

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

confidencenumber nullable

Human confidence in this decision (0.0–1.0).

reasoningstring nullable

Why this decision was made. Stored for audit trail.

payloadobject nullable

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

retriever_idstring nullable

Retriever that produced the document being annotated.

execution_idstring nullable

Retriever execution ID.

stage_namestring nullable

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

actor_idstring

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

actor_typestring

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

created_atstring date-time

updated_atstring date-time

Example response

{
  "actor_id": "user_eric",
  "actor_type": "user",
  "annotation_id": "ann_abc123def4567890",
  "collection_id": "col_notes",
  "confidence": 0.95,
  "document_id": "doc_xyz",
  "label": "approved",
  "namespace_id": "ns_vitae",
  "payload": {
    "codes_approved": [
      "E11.40",
      "E11.65"
    ],
    "raf_impact": 0.42
  },
  "reasoning": "Note clearly documents peripheral neuropathy.",
  "retriever_id": "ret_hcc_review"
}