> ## Documentation Index > Fetch the complete documentation index at: https://docs.avidoai.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a human annotation > Creates a new human annotation judgement for a trace. When verdict is false, automatically creates an Inbox issue ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/avido/openapi.documented.yml post /v0/human-annotations openapi: 3.1.1 info: title: Avido API description: >- Avido's API for LLM usage events, tool calls, trace management, webhook validation, and more. See each endpoint's request/response schema for details. version: 0.1.0 contact: name: Avido Support email: support@avidoai.com url: https://avidoai.com/support servers: - url: https://api.avidoai.com description: Production API security: - ApiKey: [] ApplicationId: [] paths: /v0/human-annotations: post: tags: - Human Annotations summary: Create a human annotation description: >- Creates a new human annotation judgement for a trace. When verdict is false, automatically creates an Inbox issue operationId: createHumanAnnotation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHumanAnnotationRequest' examples: pass: summary: Pass annotation value: traceId: 12345678-1234-1234-1234-1234567890ab verdict: true source: REVIEW_QUEUE queueItemId: abcdef01-e89b-12d3-a456-426614174000 fail: summary: Fail annotation with critique value: traceId: 12345678-1234-1234-1234-1234567890ab verdict: false critique: >- The agent answered an unrelated policy question instead of addressing the user's query about billing. source: REVIEW_QUEUE queueItemId: abcdef01-e89b-12d3-a456-426614174000 responses: '200': description: Human annotation created successfully content: application/json: schema: $ref: '#/components/schemas/HumanAnnotationResponse' '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreateHumanAnnotationRequest: type: object properties: traceId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Trace being annotated example: 12345678-1234-1234-1234-1234567890ab verdict: type: boolean description: true = pass (👍), false = fail (👎) example: true critique: description: Free-text critique. Required (≥20 characters) when verdict is false example: The agent answered an unrelated policy question. type: string minLength: 1 maxLength: 2048 source: $ref: '#/components/schemas/HumanAnnotationSource' description: Entry point used to create this annotation queueItemId: description: >- Associated queue item ID — must be provided when source is REVIEW_QUEUE and must not be provided otherwise example: abcdef01-e89b-12d3-a456-426614174000 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - traceId - verdict - source additionalProperties: false title: CreateHumanAnnotationRequest description: Request body for creating a new human annotation HumanAnnotationResponse: type: object properties: data: $ref: '#/components/schemas/HumanAnnotationOutput' required: - data additionalProperties: false title: HumanAnnotationResponse description: Successful response containing a single human annotation ValidationErrorResponse: type: object properties: message: type: string description: A human-readable error message indicating what went wrong. example: Invalid request data issues: type: array items: type: object properties: code: type: string message: type: string path: type: array items: type: string required: - code - message - path additionalProperties: false description: Array of detailed validation error objects. example: - code: invalid_string message: Invalid UUID path: - id required: - message - issues additionalProperties: false title: ValidationErrorResponse description: Details about validation errors in incoming requests. ErrorResponse: type: object properties: message: type: string description: A human-readable error message explaining the error. example: Resource not found required: - message additionalProperties: false title: ErrorResponse description: Standard error format for failed API operations. HumanAnnotationSource: type: string enum: - REVIEW_QUEUE - TRACE_PAGE - TEST_PAGE description: Where the human annotation was created from example: REVIEW_QUEUE HumanAnnotationOutput: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Unique identifier of the human annotation example: 789e4567-e89b-12d3-a456-426614174000 orgId: type: string minLength: 1 maxLength: 256 description: Organization ID that owns this annotation example: org_123456 applicationId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Application this annotation belongs to example: 456e7890-e89b-12d3-a456-426614174000 traceId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Trace this annotation evaluates example: 12345678-1234-1234-1234-1234567890ab verdict: type: boolean description: true = pass (👍), false = fail (👎) example: true critique: description: >- Free-text critique. Required (≥20 characters) when verdict is false; optional otherwise example: The agent answered an unrelated policy question. nullable: true anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' annotatorId: description: >- User ID of the annotator. Nullable because user deletion sets this to null while preserving the annotation row for audit example: user_789012 nullable: true anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' source: $ref: '#/components/schemas/HumanAnnotationSource' description: Entry point used to create this annotation queueItemId: description: Associated queue item ID — set only when source is REVIEW_QUEUE example: abcdef01-e89b-12d3-a456-426614174000 nullable: true anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' issueId: description: Associated Inbox issue ID — set when verdict is false example: fedcba98-e89b-12d3-a456-426614174000 nullable: true anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' topicId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Topic this annotation belongs to example: 789e4567-e89b-12d3-a456-426614174000 createdAt: description: When the annotation was created example: '2024-01-05T12:34:56.789Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ modifiedAt: description: When the annotation was last modified example: '2024-01-05T12:34:56.789Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - orgId - applicationId - traceId - verdict - source - topicId - createdAt - modifiedAt additionalProperties: false title: HumanAnnotation description: >- A single SME judgement recorded against a trace. Captures whether the AI response was acceptable (verdict) and an optional critique securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: Your unique Avido API key ApplicationId: type: apiKey in: header name: x-application-id description: Your unique Avido Application ID ````