--- title: "Evaluate labels" method: POST path: "/v1/labels/evaluate" tags: ["Labels"] --- # Evaluate labels `POST /v1/labels/evaluate` 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. ## Request body - V1EvaluateLabelsRequest - `contentData` V1ContentData, required — A single piece of content to be processed by the Clavata.ai API. - `contentHash` string — The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'md5::hash') - `text` string — A text string to process. - `image` string, base64 — A binary image file to process. - `imageUrl` string — A publicly-accessible URL that points to an image. - `metadata` object - `threshold` number, double — The threshold to use for truthiness. If not set a default value will be used. - `labelVersionIds` string[] — IDs of the published label versions to evaluate against. Maximum 10 per request. - `labelEvalOptions` V1LabelEvalOptions — LabelEvalOptions are options that can be set per-label to control evaluation behavior. Field numbers/types intentionally mirror PolicyEvalOptions for parity. - `bypassCache` boolean - `expedited` boolean - `bundleSize` integer - `threshold` number, double - `stack` string - `globalContext` string — Optional global context override for this evaluation call. ## Response `200` A successful response. - V1EvaluateLabelsResponse - `contentHash` string — The hash of the content that was evaluated. - `results` V1EvaluateLabelsResponseLabelResult[] — Ordered results, one per requested `label_version_ids` entry. - `labelId` string — The label this result corresponds to. - `labelVersionId` string — The label version that was evaluated. - `jobUuid` string — The job ID for this label version's evaluation. - `evaluation` LabelResultEvaluation - `score` number, double - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `threshold` number, double — 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` V1PolicyEvaluationReport — A report on the result of evaluating a policy against a piece of content/input. - `policyId` string, uuidv4 - `policyKey` string — 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. - `policyVersionId` string, uuidv4 - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `sectionEvaluationReports` PolicyEvaluationReportSectionEvaluationReport[] — Reports on the evaluation of each SECTION or LABEL block in the policy. - `name` string - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `message` string - `assertionEvaluationReports` PolicyEvaluationReportAssertionEvaluationReport[] — Each assertion in each section is evaluated - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `message` string — The text of the assertion. - `score` number, double - `exceptionEvaluationReport` PolicyEvaluationReportExceptionEvaluationReport — Outcome of an EXCEPT WHEN or UNLESS block, if present. - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `assertionEvaluationReports` PolicyEvaluationReportAssertionEvaluationReport[] — Each assertion in the exception is evaluated - … - `reviewResult` PolicyEvaluationReportReviewResult — Report on the result of a single assertion in a policy. - … - `reviewResult` PolicyEvaluationReportReviewResult — Report on the result of a single assertion in a policy. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `score` number, double - `exceptionEvaluationReport` PolicyEvaluationReportExceptionEvaluationReport — Outcome of an EXCEPT WHEN or UNLESS block, if present. - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `assertionEvaluationReports` PolicyEvaluationReportAssertionEvaluationReport[] — Each assertion in the exception is evaluated - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `message` string — The text of the assertion. - `score` number, double - `reviewResult` PolicyEvaluationReportReviewResult — Report on the result of a single assertion in a policy. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `score` number, double - `contentHash` string — The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'fnv1a128::hash-value') - `contentMetadata` object — If metadata was attached to the content when the job was created, it will be attached to the evaluation report here. - `reviewResult` PolicyEvaluationReportReviewResult — Report on the result of a single assertion in a policy. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED' — Evaluation outcome. TRUE, FALSE or FAILED. - `score` number, double - `threshold` number, double - `labelMatches` object — 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. - `tokenUsage` PolicyEvaluationReportTokenUsage — Usage related to this policy evaluation. - `inputTokens` integer — The number of tokens that were sent to the service in the form of content. - `billedTokens` integer — The number of tokens that Clavata billed for this evaluation. - `multiplier` number, float — The policy complexity multiplier that was used to calculate the final billed tokens. - `labelId` string, uuidv4 — The ID of the published label evaluated for label-based evaluation flows. - `labelVersionId` string, uuidv4 — The ID of the published label version evaluated for label-based evaluation flows. - `error` string — Populated when this individual evaluation failed (RPC may still succeed). ## Other responses - `default` — An unexpected error response. --- [API](https://skmtc.net/clavata/apis/clavata-public-api-v1.md) · [All operations](https://skmtc.net/clavata/apis/clavata-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clavata/clavata-public-api-v1/revisions/7d66607e1ab6/schema)