Our Python SDK got smarter. We developed a Typscript SDK too. We are updating our SDK code blocks. Python SDKhere.Typscript SDKhere.
Description
Patronus AI APIAnnotations

Create Annotation

Create or update an annotation.

Creates a new annotation or updates an existing one with the specified criteria and values.

For a given combination of type, reference, and annotation_criteria, this endpoint will not

create multiple objects but will update the existing annotation if one already exists.

At least one of value_pass, value_score, or value_text must be provided. The annotation

will be associated with reference object.

Examples:

Create a span annotation

          "type": "span",
          "reference": "span_id_123",
          "annotation_criteria": "d68ccc8e-9769-4d46-b8a2-e60f67b1182f",
          "value_score": 8.5,
          "explanation": "Response was helpful but could be more detailed"
      }

Create a boolean annotation for log

          "type": "log",
          "reference": "log_id_123",
          "annotation_criteria": "559b0966-8ce3-433b-8ee3-2cbcb0055d0b",
          "value_pass": true,
      }

Create a text annotation for evaluation

          "type": "evaluation",
          "reference": "evaluation_id_123",
          "annotation_criteria": "6457395d-db10-420d-8086-3fb22a40e2cc",
          "value_text": "Needs revision in section 3. Overall structure is good."
      }
POST
/v1/annotations
/v1/annotations

The Authorization access token

Authorization

X-API-KEY<token>

In: header

Request Body

application/jsonRequired

annotation_criteria
Required
Annotation Criteria

Reference to the annotation criteria to use for this annotation

Format: "uuid"

type
Required
AnnotationType

Type of the object being annotated (trace, span, log, evaluation or trace_insight)

Value in: "trace" | "span" | "log" | "trace_insight" | "evaluation"

reference
Required
Reference

Reference identifier to the object being annotated.

value_passValue Pass

Boolean value indicating whether the annotation passed or failed a criteria

value_scoreValue Score

Numerical score value for the annotation

value_textValue Text

Textual value or content for the annotation

explanationExplanation

Optional explanation or reasoning for the annotation

curl -X POST "https://api.patronus.ai/v1/annotations" \
  -H "X-API-KEY: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "annotation_criteria": "e3b6bb3c-5051-4c5b-be17-cc69f6fc2ef6",
    "type": "trace",
    "reference": "string",
    "value_pass": true,
    "value_score": 0,
    "value_text": "string",
    "explanation": "string"
  }'

Successful Response

{
  "annotation": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "annotation_criteria": "e3b6bb3c-5051-4c5b-be17-cc69f6fc2ef6",
    "type": "trace",
    "reference": "string",
    "value_pass": true,
    "value_score": 0,
    "value_text": "string",
    "explanation": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "app": "string",
    "experiment_id": 0
  }
}

Previous

Batch Delete Annotation Criteria

Next

Create Annotation Criteria