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

# Annotations SDK Reference

> SDK reference for the Annotations API, available in Node.js and Python.

## Annotations

### Create an Annotation

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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.annotations.create(trace_id="<id>", span_id="<id>", annotations=[])

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.annotations.create({
      traceId: "<id>",
      spanId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "trace_id": str,  # required
        "span_id": str,  # required
        "annotations": Union[Annotations1, Annotations2],  # required
        "metadata": {  # optional
            "identity_id": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      traceId: string;  // required
      spanId: string;  // required
      requestBody?: {
        annotations: string;  // required
        metadata?: {
          identityId?: string;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete an Annotation

Remove one or more annotations from a specific span by their evaluator keys, or remove corrections by the eval ids of their parent annotations.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.annotations.delete(trace_id="<id>", span_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.annotations.delete({
      traceId: "<id>",
      spanId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "trace_id": str,  # required
        "span_id": str,  # required
        "keys": List[str],
        "parent_annotation_ids": List[str],
        "metadata": {  # optional
            "identity_id": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      traceId: string;  // required
      spanId: string;  // required
      requestBody?: {
        keys?: string[];
        parentAnnotationIds?: string[];
        metadata?: {
          identityId?: string;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>