--- title: "Create a label version" method: POST path: "/v1/labels/{labelId}/versions" tags: ["Labels"] --- # Create a label version `POST /v1/labels/{labelId}/versions` ## Request - Base URL: `https://gateway.app.clavata.ai:8443` - URL: `https://gateway.app.clavata.ai:8443/v1/labels/{labelId}/versions` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Publishes an immutable version under the label. `text` is single-label DSL by default; set `text_format` to `TEXT_FORMAT_PLAIN_TEXT` to send a plain-language rule instead, which is stored as a single signal. Reads always return the compiled DSL, not the text that was submitted. There is no current/live version: evaluation always uses an explicit version ID. There is no PATCH or DELETE for versions. Requires a label-first account; other accounts receive `FAILED_PRECONDITION`. ## Path parameters - `labelId` string, required ## Request body - LabelsServiceCreateLabelVersionBody - `text` string - `description` string: Optional description for this version. - `parentLabelVersionId` string: Optional explicit parent/source version for lineage tracking. - `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 - `imageDetailLevel` 'IMAGE_DETAIL_LEVEL_UNSPECIFIED' | 'IMAGE_DETAIL_LEVEL_VERY_LOW' | 'IMAGE_DETAIL_LEVEL_LOW' | 'IMAGE_DETAIL_LEVEL_MEDIUM' | 'IMAGE_DETAIL_LEVEL_HIGH' | 'IMAGE_DETAIL_LEVEL_VERY_HIGH': ImageDetailLevel selects how much image detail is preserved when images are evaluated. Levels are semantic; the selected extractor's vision encoder maps each level to a model-specific token budget. Unspecified preserves the extractor's configured default. - `globalContext` string: Optional global context to store on the created label version. - `confirmDuplicate` boolean: If true, bypass the duplicate-content check. Used by clients to re-submit after the user has acknowledged a `duplicate_of` response. - `textFormat` 'TEXT_FORMAT_UNSPECIFIED' | 'TEXT_FORMAT_DSL' | 'TEXT_FORMAT_PLAIN_TEXT': How the `text` on a version-create request should be interpreted. - TEXT_FORMAT_UNSPECIFIED: Unspecified defaults to DSL for backward compatibility. - TEXT_FORMAT_DSL: Single-label V3 DSL. - TEXT_FORMAT_PLAIN_TEXT: Plain rule text, stored as a single signal. Callers using this do not need to know the DSL; the text is wrapped before compilation. ## Response `200` A successful response. - V1CreateLabelVersionResponse - `valid` boolean - `error` V1CompilationError - `message` string - `line` integer - `column` integer - `labelVersion` V1LabelVersion: LabelVersion is an immutable snapshot of a label's DSL + compiled representation. - `labelVersionId` string - `labelId` string - `text` string - `blob` string, byte - `description` string - `signalCount` integer - `totalSignalTokens` integer - `created` string, date-time - `expunged` boolean - `createdById` string - `sequentialVersion` integer - `parentLabelVersionId` string - `complexityScore` number, float - `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 - `imageDetailLevel` 'IMAGE_DETAIL_LEVEL_UNSPECIFIED' | 'IMAGE_DETAIL_LEVEL_VERY_LOW' | 'IMAGE_DETAIL_LEVEL_LOW' | 'IMAGE_DETAIL_LEVEL_MEDIUM' | 'IMAGE_DETAIL_LEVEL_HIGH' | 'IMAGE_DETAIL_LEVEL_VERY_HIGH': ImageDetailLevel selects how much image detail is preserved when images are evaluated. Levels are semantic; the selected extractor's vision encoder maps each level to a model-specific token budget. Unspecified preserves the extractor's configured default. - `globalContext` string: Optional global context to inject into LLM context window during evaluation. This provides additional context about the nature of content being evaluated. - `tokenCountsV2` V1TokenCountsV2: TokenCountsV2 groups the static V2 token counts saved alongside a policy version, label version, or user label draft. The counts are calculated together, so message presence signals that V2 accounting is available for the saved DSL. - `dslTokenCount` integer: V2 DSL-only token count for display. - `globalContextTokens` integer: V2 token count for the saved global context. - `signalTokens` integer: V2 token count for formatted DSL signals. - `signalSpecialTokens` integer: V2 token count for DSL prompt special/structural tokens. - `contentSpecialTokens` integer: V2 token count for content prompt special/structural tokens. - `duplicateOf` V1LabelVersion: LabelVersion is an immutable snapshot of a label's DSL + compiled representation. - `labelVersionId` string - `labelId` string - `text` string - `blob` string, byte - `description` string - `signalCount` integer - `totalSignalTokens` integer - `created` string, date-time - `expunged` boolean - `createdById` string - `sequentialVersion` integer - `parentLabelVersionId` string - `complexityScore` number, float - `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 - `imageDetailLevel` 'IMAGE_DETAIL_LEVEL_UNSPECIFIED' | 'IMAGE_DETAIL_LEVEL_VERY_LOW' | 'IMAGE_DETAIL_LEVEL_LOW' | 'IMAGE_DETAIL_LEVEL_MEDIUM' | 'IMAGE_DETAIL_LEVEL_HIGH' | 'IMAGE_DETAIL_LEVEL_VERY_HIGH': ImageDetailLevel selects how much image detail is preserved when images are evaluated. Levels are semantic; the selected extractor's vision encoder maps each level to a model-specific token budget. Unspecified preserves the extractor's configured default. - `globalContext` string: Optional global context to inject into LLM context window during evaluation. This provides additional context about the nature of content being evaluated. - `tokenCountsV2` V1TokenCountsV2: TokenCountsV2 groups the static V2 token counts saved alongside a policy version, label version, or user label draft. The counts are calculated together, so message presence signals that V2 accounting is available for the saved DSL. - `dslTokenCount` integer: V2 DSL-only token count for display. - `globalContextTokens` integer: V2 token count for the saved global context. - `signalTokens` integer: V2 token count for formatted DSL signals. - `signalSpecialTokens` integer: V2 token count for DSL prompt special/structural tokens. - `contentSpecialTokens` integer: V2 token count for content prompt special/structural tokens. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-09-10** `f293b5bf2c4f`: 1 info - added the new optional request property `textFormat` - **2026-09-03** `703019caec67`: 1 info - endpoint added [Operation history](https://skmtc.dev/clavata/apis/clavata-public-api-v1/changes/v1/labels/:labelId/versions/post.md) --- [API](https://skmtc.dev/clavata/apis/clavata-public-api-v1.md) - [All operations](https://skmtc.dev/clavata/apis/clavata-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/clavata/apis/clavata-public-api-v1/revisions/d7a854b0070f?raw)