openapi: 3.2.0
info:
  title: Latitude Annotations API
  version: v1
  description: Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked.
  servers:
  - url: https://api.latitude.so
    description: Production
servers:
- url: https://api.latitude.so
tags:
- name: Annotations
paths:
  /v1/projects/{projectSlug}/annotations:
    post:
      tags:
      - Annotations
      x-fern-sdk-group-name: annotations
      x-fern-sdk-method-name: create
      summary: Create project annotation
      description: 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.
      security:
      - ApiKeyAuth: []
      operationId: createAnnotation
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotationBody'
      responses:
        '201':
          description: Annotation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{projectSlug}/annotations/{annotationId}:
    get:
      tags:
      - Annotations
      x-fern-sdk-group-name: annotations
      x-fern-sdk-method-name: get
      summary: Get API annotation
      description: Returns an API-created annotation by its Latitude-generated identifier.
      security:
      - ApiKeyAuth: []
      operationId: getAnnotation
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          minLength: 24
          maxLength: 24
          description: Latitude-generated annotation identifier returned when the annotation was created.
        required: true
        description: Latitude-generated annotation identifier returned when the annotation was created.
        name: annotationId
        in: path
      responses:
        '200':
          description: Annotation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Annotations
      x-fern-sdk-group-name: annotations
      x-fern-sdk-method-name: update
      summary: Update API annotation
      description: Updates an API-created annotation while retaining its Latitude-generated identifier. Omitted fields keep their current values.
      security:
      - ApiKeyAuth: []
      operationId: updateAnnotation
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          minLength: 24
          maxLength: 24
          description: Latitude-generated annotation identifier returned when the annotation was created.
        required: true
        description: Latitude-generated annotation identifier returned when the annotation was created.
        name: annotationId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnnotationBody'
      responses:
        '200':
          description: Updated annotation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Annotations
      x-fern-sdk-group-name: annotations
      x-fern-sdk-method-name: delete
      summary: Delete API annotation
      description: Deletes an API-created annotation by its Latitude-generated identifier.
      security:
      - ApiKeyAuth: []
      operationId: deleteAnnotation
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          minLength: 24
          maxLength: 24
          description: Latitude-generated annotation identifier returned when the annotation was created.
        required: true
        description: Latitude-generated annotation identifier returned when the annotation was created.
        name: annotationId
        in: path
      responses:
        '204':
          description: Annotation deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FilterSet:
      type: object
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/FilterCondition'
      description: Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set.
    AnnotationAnchor:
      type: object
      properties:
        messageIndex:
          type: integer
          minimum: 0
          description: 0-based message index inside the conversation. Omit for conversation-level annotations.
        partIndex:
          type: integer
          minimum: 0
          description: 0-based index into the target message's `parts[]`. Requires `messageIndex`.
        startOffset:
          type: integer
          minimum: 0
          description: Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`.
        endOffset:
          type: integer
          minimum: 0
          description: Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`.
        textFormat:
          type: string
          enum:
          - pretty-json
          description: UI-side text transform applied before the offsets were captured (e.g. `"pretty-json"`). Resolvers must apply the same transform before slicing.
      description: Optional anchor pinning the annotation to a specific message / part / offset range inside the trace.
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    FilterCondition:
      type: object
      properties:
        op:
          type: string
          enum:
          - eq
          - neq
          - gt
          - gte
          - lt
          - lte
          - in
          - notIn
          - contains
          - notContains
          - gtePercentile
          description: Comparison operator applied to the field's value (e.g. `eq`, `neq`, `in`). The full operator list lives in the API reference.
        value:
          anyOf:
          - type: string
          - type: number
          - type: boolean
          - type: array
            items:
              anyOf:
              - type: string
              - type: number
          description: Right-hand value compared against the field. Arrays are required for `in` / `notIn`-style operators.
      required:
      - op
      - value
    CreateAnnotationBody:
      type: object
      properties:
        simulationId:
          type: string
          nullable: true
          minLength: 24
          maxLength: 24
          default: null
          description: Simulation this annotation is tied to, if any. `null` (default) when not part of a simulation.
        signalId:
          type: string
          nullable: true
          minLength: 24
          maxLength: 24
          default: null
          description: Pre-selected signal this annotation belongs to. Leave `null` (default) to let the automatic signal-discovery pipeline route the annotation.
        value:
          type: number
          minimum: 0
          maximum: 1
          description: Normalized score value in [0, 1]. Higher = better.
        passed:
          type: boolean
          description: Whether the annotated output passes the reviewer's bar.
        feedback:
          type: string
          minLength: 1
          description: Free-text feedback explaining the score. Surfaced alongside the trace.
        anchor:
          $ref: '#/components/schemas/AnnotationAnchor'
        trace:
          $ref: '#/components/schemas/TraceRef'
      required:
      - value
      - passed
      - feedback
      - trace
    AnnotationMetadata:
      type: object
      properties:
        rawFeedback:
          type: string
          description: Original feedback text as written by the annotator, before any server-side enrichment.
        messageIndex:
          type: integer
          minimum: 0
          description: 0-based message index inside the conversation. Omit for conversation-level annotations.
        partIndex:
          type: integer
          minimum: 0
          description: 0-based index into the target message's `parts[]`. Requires `messageIndex`.
        startOffset:
          type: integer
          minimum: 0
          description: Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`.
        endOffset:
          type: integer
          minimum: 0
          description: Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`.
        textFormat:
          type: string
          enum:
          - pretty-json
          description: UI-side text transform applied before the offsets were captured (e.g. `"pretty-json"`). Resolvers must apply the same transform before slicing.
      required:
      - rawFeedback
      description: 'Annotation-specific metadata: `rawFeedback` plus a snapshot of the anchor at write time.'
    TraceRef:
      oneOf:
      - type: object
        properties:
          by:
            type: string
            enum:
            - id
            description: Match a single trace by its identifier. Pair with `id`.
          id:
            type: string
            minLength: 32
            maxLength: 32
            description: 32-character trace identifier.
        required:
        - by
        - id
      - type: object
        properties:
          by:
            type: string
            enum:
            - filters
            description: Match a single trace by a filter set. Pair with `filters`; exactly one trace must match.
          filters:
            $ref: '#/components/schemas/FilterSet'
        required:
        - by
        - filters
      description: Target trace. Either an explicit id or a filter set matching exactly one trace.
    UpdateAnnotationBody:
      type: object
      properties:
        value:
          type: number
          minimum: 0
          maximum: 1
          description: New normalized score value in [0, 1].
        passed:
          type: boolean
          description: New pass or fail verdict.
        feedback:
          type: string
          minLength: 1
          description: New free-text feedback explaining the score.
    Annotation:
      type: object
      properties:
        id:
          type: string
          minLength: 24
          maxLength: 24
          description: Stable annotation identifier.
        organizationId:
          type: string
          minLength: 24
          maxLength: 24
          description: Organization that owns this annotation.
        projectId:
          type: string
          minLength: 24
          maxLength: 24
          description: Project this annotation lives in.
        sessionId:
          type: string
          nullable: true
          maxLength: 128
          description: Session id lifted from the annotated trace. `null` when the trace has no session.
        traceId:
          type: string
          nullable: true
          minLength: 32
          maxLength: 32
          description: Identifier of the annotated trace.
        spanId:
          type: string
          nullable: true
          minLength: 16
          maxLength: 16
          description: Span the annotation pins to. Defaults to the trace's last LLM-completion span.
        simulationId:
          type: string
          nullable: true
          minLength: 24
          maxLength: 24
          description: Simulation reference, if any.
        signalId:
          type: string
          nullable: true
          minLength: 24
          maxLength: 24
          description: Signal this annotation contributes to, if any.
        value:
          type: number
          minimum: 0
          maximum: 1
          description: Normalized score value in [0, 1]. Higher = better.
        passed:
          type: boolean
          description: Whether the annotation marks the output as passing.
        feedback:
          type: string
          description: Free-text feedback explaining the score.
        error:
          type: string
          nullable: true
          minLength: 1
          description: Generation error text, when the annotation itself errored. `null` for successful annotations.
        errored:
          type: boolean
          description: '`true` when the annotation could not be generated successfully.'
        duration:
          type: integer
          minimum: 0
          description: Generation duration in nanoseconds. `0` for human annotations.
        tokens:
          type: integer
          minimum: 0
          description: Total LLM tokens consumed generating the score. `0` for human annotations.
        cost:
          type: integer
          minimum: 0
          description: Total LLM cost in microcents (100,000,000 per USD). `0` for human annotations.
        draftedAt:
          type: string
          nullable: true
          format: date-time
          description: ISO-8601 timestamp at which the annotation was drafted. `null` for published annotations.
        annotatorId:
          type: string
          nullable: true
          minLength: 24
          maxLength: 24
          description: User who authored the annotation. `null` when not attributed to a user.
        createdAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp at which the annotation was created.
        updatedAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp of the last metadata update.
        source:
          type: string
          enum:
          - annotation
          description: Always `"annotation"` for this shape.
        sourceId:
          anyOf:
          - type: string
            enum:
            - UI
            - API
            - SYSTEM
          - type: string
            minLength: 24
            maxLength: 24
          description: Origin marker. Sentinel `"UI"` / `"API"` / `"SYSTEM"` for drafts and automation, or a CUID for authored rows.
        metadata:
          $ref: '#/components/schemas/AnnotationMetadata'
      required:
      - id
      - organizationId
      - projectId
      - sessionId
      - traceId
      - spanId
      - simulationId
      - signalId
      - value
      - passed
      - feedback
      - error
      - errored
      - duration
      - tokens
      - cost
      - draftedAt
      - annotatorId
      - createdAt
      - updatedAt
      - source
      - sourceId
      - metadata
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Organization-scoped API key, sent as `Authorization: Bearer <key>`.'
      x-fern-bearer:
        name: apiKey
        env: LATITUDE_API_KEY