Our docs got a refresh! Check out the new content and improved navigation. For detailed API reference see our Python SDK docs and TypeScript SDK.
Description
API referenceAnnotations

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