> ## Documentation Index > Fetch the complete documentation index at: https://docs.clavata.ai/llms.txt > Use this file to discover all available pages before exploring further. # Evaluate labels > Evaluate content against one or more published label versions. Returns one result per version, in request order. A label-first account is required to use this endpoint. ## OpenAPI ````yaml /openapi.json post /v1/labels/evaluate openapi: 3.0.0 info: title: Clavata Public API v1 description: Endpoints for creating and managing jobs via the Clavata Public API. version: 1.0.0 contact: name: Clavata.ai url: https://clavata.ai email: support@clavata.ai servers: - url: https://gateway.app.clavata.ai:8443 security: - Bearer_Token: [] tags: - name: Public API description: Endpoints for creating and managing jobs via the Clavata Public API. paths: /v1/labels/evaluate: post: tags: - Labels summary: Evaluate labels description: >- Evaluate content against one or more published label versions. Returns one result per version, in request order. A label-first account is required to use this endpoint. operationId: LabelsService_EvaluateLabels requestBody: content: application/json: schema: $ref: '#/components/schemas/v1EvaluateLabelsRequest' required: true responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v1EvaluateLabelsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/rpcStatus' components: schemas: v1EvaluateLabelsRequest: type: object properties: contentData: $ref: '#/components/schemas/v1ContentData' threshold: type: number format: double description: >- The threshold to use for truthiness. If not set a default value will be used. labelVersionIds: type: array items: type: string description: >- IDs of the published label versions to evaluate against. Maximum 10 per request. title: Label version IDs labelEvalOptions: $ref: '#/components/schemas/v1LabelEvalOptions' globalContext: type: string description: Optional global context override for this evaluation call. required: - contentData v1EvaluateLabelsResponse: type: object properties: contentHash: type: string description: The hash of the content that was evaluated. results: type: array items: $ref: '#/components/schemas/v1EvaluateLabelsResponseLabelResult' description: Ordered results, one per requested `label_version_ids` entry. rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' v1ContentData: type: object properties: contentHash: type: string description: >- The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'md5::hash') title: Clavata calculated hash of the content. readOnly: true text: type: string description: A text string to process. title: Input text writeOnly: true image: type: string format: base64 description: A binary image file to process. title: Input image writeOnly: true imageUrl: type: string description: A publicly-accessible URL that points to an image. title: Input image URL writeOnly: true metadata: type: object additionalProperties: type: string title: Optional metadata attached to content when sent to the server description: A single piece of content to be processed by the Clavata.ai API. title: Content Data v1LabelEvalOptions: type: object properties: bypassCache: type: boolean title: Whether to bypass the query cache during evaluation expedited: type: boolean title: Whether to use expedited evaluation (prioritizing speed over cost) bundleSize: type: integer format: int64 title: The bundle size to use for query batching in Hermes threshold: type: number format: double title: The threshold to use for determining truthiness stack: type: string title: >- The stack name to use for evaluation (overrides default stack in Hermes) description: >- LabelEvalOptions are options that can be set per-label to control evaluation behavior. Field numbers/types intentionally mirror PolicyEvalOptions for parity. v1EvaluateLabelsResponseLabelResult: type: object properties: labelId: type: string description: The label this result corresponds to. labelVersionId: type: string description: The label version that was evaluated. jobUuid: type: string description: The job ID for this label version's evaluation. evaluation: $ref: '#/components/schemas/LabelResultEvaluation' error: type: string description: >- Populated when this individual evaluation failed (RPC may still succeed). description: >- Per-label result, one per requested `label_version_ids` entry (same order). Each label version gets its own job for clean recordkeeping. protobufAny: type: object properties: '@type': type: string additionalProperties: {} LabelResultEvaluation: type: object properties: score: type: number format: double outcome: $ref: '#/components/schemas/v1Outcome' threshold: type: number format: double description: >- Effective threshold used for this evaluation. When the request sets threshold to 0.0 or leaves it unset, the server substitutes `evaluation.default_threshold` (currently 0.5) per `chooseThreshold`. report: $ref: '#/components/schemas/v1PolicyEvaluationReport' v1Outcome: type: string enum: - OUTCOME_UNSPECIFIED - OUTCOME_FALSE - OUTCOME_TRUE - OUTCOME_FAILED default: OUTCOME_UNSPECIFIED description: Evaluation outcome. TRUE, FALSE or FAILED. v1PolicyEvaluationReport: type: object properties: policyId: type: string format: uuidv4 title: The ID of a policy policyKey: type: string description: >- This is the title of the policy as it appears in the policy editor. Do not use this to identify a policy. Use the policy_id instead. title: The human-readable name of the policy. policyVersionId: type: string format: uuidv4 title: The ID of a policy version result: $ref: '#/components/schemas/v1Outcome' sectionEvaluationReports: type: array items: $ref: '#/components/schemas/PolicyEvaluationReportSectionEvaluationReport' description: >- Reports on the evaluation of each SECTION or LABEL block in the policy. title: SECTION or LABEL reports exceptionEvaluationReport: $ref: '#/components/schemas/PolicyEvaluationReportExceptionEvaluationReport' contentHash: type: string description: >- The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'fnv1a128::hash-value') title: Hash of the input content contentMetadata: type: object additionalProperties: type: string description: >- If metadata was attached to the content when the job was created, it will be attached to the evaluation report here. reviewResult: $ref: '#/components/schemas/PolicyEvaluationReportReviewResult' threshold: type: number format: double title: The threshold that was used to evaluate the policy labelMatches: type: object additionalProperties: type: number format: float description: >- Labels that matched the content. The keys of the map are the label names, and the values are the scores for each label. This field provides a simple way to identify which labels matched the content without the need to dig into each section report. title: Label matches tokenUsage: $ref: '#/components/schemas/PolicyEvaluationReportTokenUsage' labelId: type: string format: uuidv4 description: >- The ID of the published label evaluated for label-based evaluation flows. title: The ID of a label labelVersionId: type: string format: uuidv4 description: >- The ID of the published label version evaluated for label-based evaluation flows. title: The ID of a label version description: >- A report on the result of evaluating a policy against a piece of content/input. title: Policy Evaluation Report PolicyEvaluationReportSectionEvaluationReport: type: object properties: name: type: string result: $ref: '#/components/schemas/v1Outcome' message: type: string assertionEvaluationReports: type: array items: $ref: >- #/components/schemas/PolicyEvaluationReportAssertionEvaluationReport description: Each assertion in each section is evaluated title: Per-assertion report exceptionEvaluationReport: $ref: '#/components/schemas/PolicyEvaluationReportExceptionEvaluationReport' reviewResult: $ref: '#/components/schemas/PolicyEvaluationReportReviewResult' description: Report on the evaluation of a SECTION or LABEL in a policy. PolicyEvaluationReportExceptionEvaluationReport: type: object properties: result: $ref: '#/components/schemas/v1Outcome' assertionEvaluationReports: type: array items: $ref: >- #/components/schemas/PolicyEvaluationReportAssertionEvaluationReport description: Each assertion in the exception is evaluated title: Per-assertion report reviewResult: $ref: '#/components/schemas/PolicyEvaluationReportReviewResult' description: Outcome of an EXCEPT WHEN or UNLESS block, if present. title: EXCEPT WHEN or UNLESS report PolicyEvaluationReportReviewResult: type: object properties: outcome: $ref: '#/components/schemas/v1Outcome' score: type: number format: double description: Report on the result of a single assertion in a policy. PolicyEvaluationReportTokenUsage: type: object properties: inputTokens: type: integer format: int32 description: >- The number of tokens that were sent to the service in the form of content. billedTokens: type: integer format: int32 description: The number of tokens that Clavata billed for this evaluation. multiplier: type: number format: float description: >- The policy complexity multiplier that was used to calculate the final billed tokens. description: Usage related to this policy evaluation. PolicyEvaluationReportAssertionEvaluationReport: type: object properties: result: $ref: '#/components/schemas/v1Outcome' message: type: string description: The text of the assertion. score: type: number format: double title: The truthiness of the assertion securitySchemes: Bearer_Token: type: http scheme: bearer bearerFormat: JWT ````