Sign in

v64

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-03124241726.5 KB
Annotations

Create project annotation

Creates a published annotation score against a target trace. The trace is resolved by explicit id (trace.by = "id") or by a filter set (trace.by = "filters", exactly one match required). When called with an OAuth token, the annotation is attributed to the authenticated user.

post/v1/projects/{projectSlug}/annotations

Path parameters

projectSlugstring required

Project slug (human-readable identifier)

Project slug (human-readable identifier)

Request body

simulationIdstring nullable

Simulation this annotation is tied to, if any. null (default) when not part of a simulation.

signalIdstring nullable

Pre-selected signal this annotation belongs to. Leave null (default) to let the automatic signal-discovery pipeline route the annotation.

valuenumber required

Normalized score value in [0, 1]. Higher = better.

passedboolean required

Whether the annotated output passes the reviewer's bar.

feedbackstring required

Free-text feedback explaining the score. Surfaced alongside the trace.

Response

Annotation created

idstring required

Stable annotation identifier.

organizationIdstring required

Organization that owns this annotation.

projectIdstring required

Project this annotation lives in.

sessionIdstring nullable required

Session id lifted from the annotated trace. null when the trace has no session.

traceIdstring nullable required

Identifier of the annotated trace.

spanIdstring nullable required

Span the annotation pins to. Defaults to the trace's last LLM-completion span.

simulationIdstring nullable required

Simulation reference, if any.

signalIdstring nullable required

Signal this annotation contributes to, if any.

valuenumber required

Normalized score value in [0, 1]. Higher = better.

passedboolean required

Whether the annotation marks the output as passing.

feedbackstring required

Free-text feedback explaining the score.

errorstring nullable required

Generation error text, when the annotation itself errored. null for successful annotations.

erroredboolean required

true when the annotation could not be generated successfully.

durationinteger required

Generation duration in nanoseconds. 0 for human annotations.

tokensinteger required

Total LLM tokens consumed generating the score. 0 for human annotations.

costinteger required

Total LLM cost in microcents (1/1,000,000 USD). 0 for human annotations.

draftedAtstring date-time nullable required

ISO-8601 timestamp at which the annotation was drafted. null for published annotations.

annotatorIdstring nullable required

User who authored the annotation. null when not attributed to a user.

createdAtstring date-time required

ISO-8601 timestamp at which the annotation was created.

updatedAtstring date-time required

ISO-8601 timestamp of the last metadata update.

source'annotation' required

Always "annotation" for this shape.