> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotate a span

> Attach one or more annotations to a specific span. A standard annotation references a human review by key and supplies a value. A correction references an existing evaluator output by parent_annotation_id and supplies the corrected value, validated against that evaluator's output schema.

> [!NOTE]
>
> **Guia relacionado**: Guia de anotações. Consulte o [Guia de anotações](/docs/pt-BR/ai-studio/observability/annotations.md) para ver um passo a passo com exemplos.

Os parâmetros de caminho `trace_id` e `span_id` identificam o span a ser anotado. Obtenha-os no [objeto `telemetry`](/docs/pt-BR/ai-gateway/features/responses-api#telemetry) de uma resposta do router, nos cabeçalhos de resposta `x-orq-trace-id` e `x-orq-trace-span-id` ou na visualização [Traces](/docs/pt-BR/ai-studio/observability/traces.md).


## OpenAPI

````yaml post /v2/traces/{trace_id}/spans/{span_id}/annotation
openapi: 3.1.0
info:
  title: Toqan Router API
  version: '2.0'
  description: Toqan Router API documentation
servers:
  - url: https://router.toqan.ai/eu
    description: Frankfurt (Europe)
  - url: https://router.toqan.ai/br
    description: São Paulo (Brazil)
security:
  - ApiKey: []
tags:
  - description: >-
      API keys authenticate programmatic access to the workspace. They expose
      opaque tokens, per-domain access grants, and budget and rate-limit
      constraints.
    name: API keys
  - name: Logs
    description: >-
      OpenTelemetry log query API. Search, filter, aggregate, and facet log
      records ingested via OTLP.
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
  - name: Telemetry
    description: >-
      Unified query envelope for traces, metrics, and logs. One request shape,
      one filter dialect, and one response shape per source, validated by a
      per-source registry.
  - name: Traces
    description: >-
      Query and inspect ingested trace data: search trace summaries, aggregate
      metrics, and read individual traces and their spans.
  - name: Views
    description: Saved filters and columns for workspace observability pages.
  - description: List models available through the AI Router.
    name: Models
  - name: Alerts
    description: >-
      Alerts evaluate a telemetry metric on a fixed interval and fire
      notifications through notifiers when the value breaches a threshold. Each
      breach opens a trigger that tracks the incident until the value recovers.
  - name: Annotation Queues
    description: Annotation queues collect spans for human review.
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, API key, provider, and model. Every
      applicable budget is enforced, and the most restrictive limit applies per
      dimension.
  - name: Files
    description: File upload and retrieval operations.
  - name: Guardrail Rules
    description: >-
      Guardrail Rules conditionally enforce evaluators and plugins for AI
      Gateway traffic. Rules may be scoped to a project or the whole workspace.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Management keys
    description: >-
      Management keys are workspace-scoped credentials that authenticate
      programmatic access to workspace administration surfaces (API keys,
      budgets). Unlike project-scoped API keys, a management key always operates
      at the workspace level.
  - name: MCP Gateway
    description: >-
      Register upstream MCP servers, discover and sync their tools, and assemble
      gateways that expose a curated tool surface to MCP clients.
  - name: Model Catalog
    description: >-
      Browse the Toqan Router model catalog: every model Toqan Router offers,
      across every provider, with pricing, capabilities and benchmark data. List
      endpoints only return models that are not deprecated. This API is public,
      requires no authentication, and is rate limited to 120 requests per minute
      per IP. Responses carry a 5-minute cache-control max-age.
  - name: Monitors
    description: >-
      Monitors are custom observability dashboards for traces, runtime metrics,
      and logs. Each monitor holds widgets that chart one telemetry query. List
      the metrics, operations, and dimensions available to your workspace with
      `GET /v3/telemetry/capabilities`, or start from a preset with `GET
      /v2/monitors/presets`.
  - name: Notifiers
    description: Notifier destinations used to send delivery and workflow notifications.
  - name: Routing Rules
    description: >-
      Routing Rules conditionally select models and enforce request plugins for
      AI Gateway traffic. Rules are evaluated by ascending priority and may be
      scoped to a project or the whole workspace.
  - name: Threads
    description: Threads group related trace invocations and their aggregate usage
  - name: Smart Routers
    description: >-
      Create and manage workspace Smart Routers. A Smart Router selects a model
      from an eligible pool for each request according to a quality, balanced,
      or cost profile.
  - name: Responses
  - name: Embeddings
  - description: Beta. Run typed classification questions against a classify model.
    name: Classify
  - description: Beta. Run classification decisions with the classify contract.
    name: Decisions
  - description: >-
      Run large offline workloads as JSONL batches and download
      OpenAI-compatible result files.
    name: Batches
paths:
  /v2/traces/{trace_id}/spans/{span_id}/annotation:
    post:
      tags: []
      summary: Annotate a span
      description: >-
        Attach one or more annotations to a specific span. A standard annotation
        references a human review by key and supplies a value. A correction
        references an existing evaluator output by parent_annotation_id and
        supplies the corrected value, validated against that evaluator's output
        schema.
      operationId: CreateAnnotation
      parameters:
        - name: trace_id
          in: path
          description: Unique identifier of the trace
          required: true
          schema:
            type: string
        - name: span_id
          in: path
          description: Unique identifier of the span
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                annotations:
                  type: array
                  items:
                    anyOf:
                      - type: object
                        properties:
                          key:
                            type: string
                            description: Unique key of the review.
                          value:
                            anyOf:
                              - type: string
                                minLength: 0
                                maxLength: 3000
                              - type: number
                              - type: boolean
                              - type: array
                                items:
                                  type: string
                                minItems: 1
                            description: >-
                              The feedback value. For single-select, provide a
                              string or single-element array. For multi-select,
                              provide an array of strings. For range
                              evaluations, provide a number. For boolean,
                              provide a boolean. For text/correction, provide a
                              string.
                        required:
                          - key
                          - value
                        additionalProperties: false
                      - type: object
                        properties:
                          parent_annotation_id:
                            type: string
                            description: >-
                              The eval id of the evaluator annotation being
                              corrected.
                          value:
                            anyOf:
                              - type: string
                                minLength: 0
                                maxLength: 3000
                              - type: number
                              - type: boolean
                              - type: array
                                items:
                                  type: string
                                minItems: 1
                            description: >-
                              The feedback value. For single-select, provide a
                              string or single-element array. For multi-select,
                              provide an array of strings. For range
                              evaluations, provide a number. For boolean,
                              provide a boolean. For text/correction, provide a
                              string.
                          explanation:
                            type: string
                            maxLength: 3000
                            description: Optional explanation for the correction.
                        required:
                          - parent_annotation_id
                          - value
                        additionalProperties: false
                  minItems: 1
                  maxItems: 10
                metadata:
                  type: object
                  properties:
                    identity_id:
                      type: string
              required:
                - annotations
        required: true
      responses:
        '200':
          description: Span annotated
        '401':
          description: >-
            Authentication required. See
            https://router.toqan.ai/docs/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: integer
          description: Numeric error code, when one is available.
        details:
          type: array
          items: {}
          description: Additional error details, when the service reports any.
      required:
        - message
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.