---
title: "Create a label"
method: POST
path: "/v1/labels"
tags: ["Labels"]
---

# Create a label

`POST /v1/labels`

Creates a label in the authenticated account. Optionally compiles and publishes an initial version from `initial_version_text`. A label with no versions is a valid state. Evaluation is always by version ID (`POST /v1/labels/evaluate`); a label with no versions has nothing to evaluate, and that endpoint requires `label_version_ids`.

## Request body

- V1CreateLabelRequest
  - `name` string
  - `initialVersionText` string
  - `description` string — Optional description for the initial version.
  - `disabled` boolean — Optional: initial disabled state (default false).
  - `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 initial label version.

## Response `200`

A successful response.

- V1CreateLabelResponse
  - `valid` boolean
  - `error` V1CompilationError
    - `message` string
    - `line` integer
    - `column` integer
  - `label` Sharedv1Label — Label is a first-class, referenceable label entity (V2). Labels can be policy-scoped (policy_id set) or independent (policy_id empty). Policy-scoped labels are uniquely identified by (customer_id, name, policy_id). Independent labels are uniquely identified by (customer_id, name).
    - `labelId` string
    - `name` string
    - `customerId` string
    - `policyId` string
    - `disabled` boolean
    - `created` string, date-time
    - `updated` string, date-time
    - `expunged` boolean
    - `description` string
    - `archivedAt` string, date-time
    - `tags` V1LabelTag[]
      - `labelTagId` string
      - `customerId` string
      - `name` string
      - `color` string
      - `created` string, date-time
      - `updated` string, date-time
      - `expunged` boolean
    - `importProvenance` V1LabelImportProvenance — LabelImportProvenance records where a label's library-derived lineage began. Set on labels created via LabelLibraryService.ImportLibraryLabel and preserved on clones derived from them.
      - `libraryLabelId` string — Opaque source library catalog id (library_labels.id).
      - `libraryVersionId` string — The library label version id that was imported (the pinned published version).
      - `libraryName` string — The library entry's display name at import time (denormalized for stable display).
      - `importedAt` string, date-time — When the original import happened.
  - `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.

## Other responses

- `default` — An unexpected error response.

## Changes

- **2026-09-03** `703019caec67` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/clavata/apis/clavata-public-api-v1/changes/v1/labels/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-service-production.skmtc.workers.dev/v1/apis/clavata/clavata-public-api-v1/revisions/703019caec67/schema)