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

# Annotations API

> Aplique feedback estruturado a traces e spans pela Annotations API. Adicione avaliações, tags de defeito, correções e substituições de resultados de evaluators de forma programática.

Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) e a referência da API para os formatos completos de solicitação e resposta.

A **Annotations API** anexa valores estruturados de revisão humana ao Trace e ao span de uma solicitação concluída. Enquanto a página [Annotations](/docs/pt-BR/ai-studio/observability/annotations.md) aborda os fluxos de revisão do **AI Studio** (o painel **Annotations** em [Traces](/docs/pt-BR/ai-studio/observability/traces.md) e Logs, as [Annotation Queues](/docs/pt-BR/ai-studio/observability/annotation-queues.md) e os experimentos), esta página é o guia de uso da API: como capturar os identificadores, montar o corpo da solicitação e tratar a resposta.

## Casos de uso

> [accordion] Avaliações programáticas
>
> Registre avaliações positivas/negativas ou categóricas de forma programática à medida que os usuários interagem com as respostas, sem abrir o **AI Studio**.

> [accordion] Registro de defeitos
>
> Registre em escala tags de defeito estruturadas, como alucinação, fuga do tema ou resposta incompleta, para uma análise sistemática de qualidade.

> [accordion] Correções de respostas
>
> Armazene uma resposta corrigida junto com a original para criar pares de referência para datasets de avaliação.

> [accordion] Substituição de resultados de evaluators
>
> Corrija um resultado de LLM-as-a-judge com uma revisão humana, anexando uma explicação à saída corrigida.

## Anexar Annotations a um span

Cada anotação precisa ser definida antes de poder ser aplicada. A definição estabelece a chave, o título e o tipo de valor; toda anotação enviada pela API precisa corresponder a uma dessas definições, e uma chave que não existe no workspace é rejeitada com um **404**. Crie as definições em **Optimization > Annotations** no **AI Studio** ou em **Settings > Annotations** no **AI Gateway**, conforme descrito na página [Annotations](/docs/pt-BR/ai-studio/observability/annotations.md).

Com a definição pronta, são duas etapas:

1. Capture o `trace_id` e o `span_id` da execução a ser anotada. Ambos são obrigatórios, e a origem deles depende do endpoint; consulte [De onde vêm os identificadores](#where-the-identifiers-come-from).
2. Envie as anotações com a [API Annotate a Span](/docs/pt-BR/reference/annotations/annotate-a-span.md), usando a `key` de uma definição de anotação existente.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "star-rating",
        "value": 4
      }
    ]
  }'
```

> [!NOTE]
>
> Algumas mensagens de erro da API ainda se referem às anotações como **human reviews**. Os dois nomes descrevem o mesmo objeto: as anotações antes se chamavam human reviews, e uma mensagem como `The human review with key "star-rating" ... was not found.` se refere à definição de anotação com essa chave.

> [!NOTE]
>
> As anotações estão disponíveis em spans de chat completion e da Responses API. Ao anotar um span de deployment, o log associado é anotado automaticamente com os mesmos valores.

## De onde vêm os identificadores

Toda execução retorna os dois ids. Quando o corpo da resposta contém um objeto `telemetry`, obtenha-os dele; caso contrário, obtenha-os dos cabeçalhos da resposta:

| Endpoint | `trace_id` | `span_id` |
| - | - | - |
| `POST /v3/router/responses` | `telemetry.trace_id` no corpo ou o cabeçalho `x-orq-trace-id` | `telemetry.span_id` no corpo ou o cabeçalho `x-orq-trace-span-id` |
| `POST /v3/router/responses` com `model: "agent/<key>"` | `telemetry.trace_id` no corpo ou o cabeçalho `x-orq-trace-id` | `telemetry.span_id` no corpo ou o cabeçalho `x-orq-trace-span-id` |
| Outros endpoints `/v3/router/*` (chat completions, completions, embeddings, images, moderations, rerank, speech, transcriptions, translations, ocr) | Cabeçalho `x-orq-trace-id` | Cabeçalho `x-orq-trace-span-id` |
| `POST /v2/deployments/invoke` | `telemetry.trace_id` no corpo | `telemetry.span_id` no corpo |

O objeto `telemetry` fica no nível superior da resposta:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "telemetry": {
    "trace_id": "01M1H2VST506ZX2WE8KDQTRBEQ",
    "span_id": "01M1H2VST543YJ5DN5RXW1B6EC"
  }
}
```

> [!WARNING]
>
> Em `POST /v2/deployments/invoke`, o cabeçalho `x-orq-trace-id` **não** contém o id do trace. Ele contém o id da execução do workflow, que identifica o span raiz da execução; `x-orq-workflow-run-id` e o campo `id` da resposta têm o mesmo valor. Use `telemetry.trace_id` do corpo da resposta como `trace_id` — passar o valor do cabeçalho retorna um 404.

> [!NOTE]
>
> Os dois ids são comparados como strings opacas: a Annotations API faz uma correspondência exata de string com os ids armazenados e não aplica nenhuma validação de formato. O formato deles é um detalhe de implementação que pode variar entre execuções, então não valide sua forma nem presuma um comprimento fixo.

## Campos de Annotations

Os campos marcados com `*` são sempre obrigatórios. `key` e `parent_annotation_id` são obrigatórios condicionalmente: cada entrada contém exatamente um deles.

| Campo | Local | Tipo | Descrição |
| - | - | - | - |
| `trace_id*` | path | string | O id do trace ao qual o span pertence, obtido da resposta da execução; consulte [De onde vêm os identificadores](#where-the-identifiers-come-from) |
| `span_id*` | path | string | O id do span que está sendo anotado, obtido da resposta da execução; consulte [De onde vêm os identificadores](#where-the-identifiers-come-from) |
| `annotations*` | body | array | As anotações a serem aplicadas, entre 1 e 10 por solicitação |
| `annotations[].key` | body | string | A chave de uma definição de anotação existente. Obrigatória para uma anotação padrão e não aceita em uma correção |
| `annotations[].value*` | body | string, number, boolean ou array de strings | O valor da anotação; o tipo depende da definição da anotação (veja abaixo) |
| `annotations[].parent_annotation_id` | body | string | O eval id da anotação de evaluator que está sendo corrigida. Obrigatório para uma correção e não aceito em uma anotação padrão |
| `annotations[].explanation` | body | string | Explicação opcional para uma correção, com até 3000 caracteres |
| `metadata.identity_id` | body | string | Identidade opcional do revisor para atribuição; use `identityId` no SDK para Node |

Uma entrada de anotação é uma **anotação padrão**, com `key` e `value`, ou uma **correção**, com `parent_annotation_id`, `value` e, opcionalmente, `explanation`. Os dois formatos são mutuamente exclusivos.

## Valores de Annotations

O tipo de `value` deve corresponder à definição da anotação:

* **Categórica, seleção única**: uma string ou um array com um único elemento, por exemplo `"good"` ou `["good"]`
* **Categórica, seleção múltipla**: um array de strings, por exemplo `["grammatical", "hallucination"]`
* **Intervalo**: um número dentro do mínimo/máximo configurado para a anotação, por exemplo `4` em um intervalo de 1 a 5
* **Booleana**: `true` ou `false`
* **Texto ou correção**: uma string com até 3000 caracteres

Valores de string fora das opções configuradas para a anotação são rejeitados; consulte [Tratamento de erros](#error-handling).

## Correções

Uma correção substitui uma saída existente de evaluator por um valor revisado por uma pessoa:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "parent_annotation_id": "<evaluator_annotation_id>",
        "value": false,
        "explanation": "The response omitted a required disclaimer."
      }
    ]
  }'
```

> [!NOTE]
>
> O `value` corrigido deve corresponder ao tipo de saída da própria anotação de evaluator. Consulte [Corrigir um resultado de Evaluator](/docs/pt-BR/ai-studio/observability/traces.md#correct-an-evaluator-result) para ver o equivalente na interface.

## Annotations em lote

Envie até 10 entradas de anotação em uma única solicitação:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "rating",
        "value": "good"
      },
      {
        "key": "star-rating",
        "value": 4
      },
      {
        "key": "categories",
        "value": ["helpful", "accurate", "concise"]
      }
    ]
  }'
```

## Remover Annotations

Envie `keys` para a [API Remove an Annotation from a Span](/docs/pt-BR/reference/annotations/remove-an-annotation-from-a-span.md) para excluir anotações padrão, ou `parent_annotation_ids` para excluir correções pelos eval ids das anotações pai. Até 10 de cada por solicitação.

Os exemplos abaixo mostram `keys`; para excluir uma correção, substitua o corpo por `{"parent_annotation_ids": ["<evaluator_annotation_id>"]}`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X DELETE "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["rating", "defects"]
  }'
```

## Onde as Annotations aparecem

As anotações aplicadas pela API aparecem no painel **Annotations** das visualizações de detalhes de span e de log em [Traces](/docs/pt-BR/ai-studio/observability/traces.md) e Logs.

## Tratamento de erros

| Código de status | Erro | Exemplo de mensagem | Solução |
| - | - | - | - |
| **404** | Annotation não encontrada | `The human review with key "star-rating" for workspace abc123 was not found.` | Crie uma Annotation com a chave especificada antes de anotar. |
| **404** | Span não encontrado | `Span with id xyz789 and trace id trace456 for workspace abc123 was not found.` | Verifique se o `trace_id` e o `span_id` estão corretos e pertencem ao workspace. Se os ids estiverem corretos e a solicitação vier logo após a chamada que a gerou, tente novamente com um breve backoff: a ingestão de spans é assíncrona e pode ainda não ter sido concluída. |
| **400** | Valor inválido | `Invalid value: poor. Valid options are: good, bad.` | Garanta que o valor corresponda às opções definidas na Annotation. |
| **400** | Valor fora do intervalo | `Value 15 is out of range [0, 10].` | Informe um número dentro do intervalo mínimo/máximo definido para a Annotation. |
| **400** | String longa demais | Erro de validação da solicitação em `annotations[].value` | Mantenha os valores de string dentro de 3000 caracteres. |

Veja um ciclo de feedback completo implementado do zero. Leia nosso cookbook Capturing User Feedback.

## Restrições

* **Limites de lote**: até 10 anotações por solicitação de criação e até 10 chaves e 10 `parent_annotation_ids` por solicitação de exclusão
* **Comprimento do valor**: os valores de string são limitados a 3000 caracteres; as definições de anotação não impõem um limite menor
* **Campos de metadados**: o objeto opcional `metadata` aceita `identity_id` (`identityId` no SDK para Node) para atribuição do revisor

## Veja também

* [Annotations](/docs/pt-BR/ai-studio/observability/annotations.md): os fluxos de revisão do **AI Studio**
* [Annotation Queues](/docs/pt-BR/ai-studio/observability/annotation-queues.md): fluxos de revisão em lote
* Referência do SDK de Annotations: assinaturas dos métodos do SDK


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