> ## Documentation Index > Fetch the complete documentation index at: https://docs.attention.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Label > Creates a new label in the caller's organization. The label name must be unique within the organization; attempting to create a duplicate returns 409. On a network retry after a successful first request, clients may observe a 409 and should fetch the label by name to confirm creation. ## OpenAPI ````yaml post /labels openapi: 3.0.1 info: title: Attention Service V2 description: Attention Service API V2 termsOfService: https://www.attention.com/terms-of-use contact: name: Attention Team url: https://docs.attention.com/welcome email: support@attention.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.8.0 servers: - url: https://api.attention.tech/v2 security: - APIKeyHeader: [] paths: /labels: post: tags: - Label summary: Create Label description: >- Creates a new label in the caller's organization. The label name must be unique within the organization; attempting to create a duplicate returns 409. On a network retry after a successful first request, clients may observe a 409 and should fetch the label by name to confirm creation. operationId: createLabel requestBody: description: Details of the label to create. content: application/json: schema: $ref: '#/components/schemas/CreateLabelRequest' application/vnd.api+json: schema: $ref: '#/components/schemas/CreateLabelRequest' required: true responses: '201': description: Label successfully created content: application/json: schema: $ref: '#/components/schemas/LabelResponse' application/vnd.api+json: schema: $ref: '#/components/schemas/LabelResponse' '400': description: >- Invalid request body (missing name, name too long, description too long, or invalid option shape) content: application/json: schema: $ref: '#/components/schemas/Error' example: id: invalid_parameter status: '400' code: '400' title: Invalid Parameter detail: name must be between 1 and 128 characters application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '401': description: >- Authentication failed. Please provide a valid organization-scoped API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: id: unauthorized status: '401' code: '401' title: Unauthorized detail: Valid organization-scoped API key required application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '409': description: A label with the same name already exists in the organization content: application/json: schema: $ref: '#/components/schemas/Error' example: id: conflict status: '409' code: '409' title: Conflict detail: A label with this name already exists in the organization application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '422': description: >- Schema-level validation failure (e.g. body fails minLength/maxLength). Returned before handler-level business rules are applied. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 604 message: name in body should be at least 1 chars long application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '500': description: Unexpected server error. Please try again later. content: application/json: schema: $ref: '#/components/schemas/Error' application/vnd.api+json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error occurred while creating the label content: application/json: schema: $ref: '#/components/schemas/Error' application/vnd.api+json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateLabelRequest: required: - name type: object properties: name: maxLength: 128 minLength: 1 type: string description: >- Human-readable label name. Trimmed before validation. Must be unique within the organization. example: Buying Signal description: maxLength: 2000 type: string description: Optional description of the label. 0 to 2000 characters. example: Conversations where the prospect expresses a buying signal. aiFlow: type: boolean description: >- Whether this label participates in the AI flow (auto-classification during conversation post-processing). Defaults to false. example: true allTeams: type: boolean description: >- Whether this label applies to all teams in the organization. Defaults to false. example: false options: type: array description: >- Optional set of selectable values when the label is a multi-value enum. Omit or send an empty array for binary labels. items: $ref: '#/components/schemas/LabelOption' description: >- Payload for creating a new label in the authenticated organization. The organization UUID is derived from the API key and must not be supplied in the body. example: name: Buying Signal description: Conversations where the prospect expresses a buying signal. aiFlow: true allTeams: false options: - value: high-intent description: Prospect has explicit buying signals LabelResponse: type: object properties: data: $ref: '#/components/schemas/Label' description: Single-resource response envelope for label endpoints. example: data: uuid: fe515723-fe2e-4959-a5fa-c4d3937fe7e4 name: Buying Signal description: Conversations where the prospect expresses a buying signal. aiFlow: true allTeams: false isDefaultTemplate: false options: [] organizationUUID: 16b78cec-82ef-46d2-8213-5d3bb7d2571c createdAt: '2026-04-16T18:00:00Z' Error: type: object properties: id: type: string description: A unique identifier for the error. status: type: string description: >- The HTTP status code applicable to this problem, expressed as a string value. code: type: string description: An application-specific error code, expressed as a string value. title: type: string description: A short, human-readable summary of the problem. detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem. source: type: object properties: pointer: type: string parameter: type: string meta: type: object properties: {} example: id: not_found_error status: '404' code: '404' title: Not Found Error detail: The requested resource was not found source: pointer: /data/attributes/id LabelOption: type: object properties: value: type: string description: >- The option value as displayed to callers. Stored as an arbitrary JSON value server-side; surfaced here as a string for REST ergonomics. example: high-intent description: type: string description: >- Optional human-readable description of the option, used for tooltips and AI-flow prompts. example: Prospect has explicit buying signals description: >- A single selectable value within a label's option set. Present when the label is configured as a multi-value enum. example: value: high-intent description: Prospect has explicit buying signals Label: required: - aiFlow - allTeams - createdAt - isDefaultTemplate - name - organizationUUID - uuid type: object properties: uuid: type: string description: Unique identifier of the label. example: fe515723-fe2e-4959-a5fa-c4d3937fe7e4 name: type: string description: >- Human-readable label name. Unique per organization. Trimmed; 1 to 128 characters. example: Buying Signal description: type: string description: >- Longer description of the label's meaning or criteria. 0 to 2000 characters. example: Conversations where the prospect expresses a buying signal. aiFlow: type: boolean description: >- Whether this label participates in the AI flow (auto-classification during conversation post-processing). example: true allTeams: type: boolean description: >- Whether this label applies to all teams in the organization. When false, label visibility is constrained by team assignments managed through the internal API. example: false isDefaultTemplate: type: boolean description: >- Whether this label originated from the organization's default template. Default-template labels are typically managed as a system-seeded group. example: false options: type: array description: >- Optional set of selectable values when the label is a multi-value enum. Empty or omitted for binary labels. items: $ref: '#/components/schemas/LabelOption' organizationUUID: type: string description: >- UUID of the organization that owns the label. Always matches the authenticated principal's organization on responses. example: 16b78cec-82ef-46d2-8213-5d3bb7d2571c createdAt: type: string description: Timestamp when the label was created, in ISO 8601 (RFC 3339) format. format: date-time example: '2026-04-16T18:00:00Z' description: >- A label (label category) used to classify conversations and drive AI flows, scorecard criteria, and intelligence-item-collection criteria. Labels are scoped to a single organization. example: uuid: fe515723-fe2e-4959-a5fa-c4d3937fe7e4 name: Buying Signal description: Conversations where the prospect expresses a buying signal. aiFlow: true allTeams: false isDefaultTemplate: false options: - value: high-intent description: Prospect has explicit buying signals organizationUUID: 16b78cec-82ef-46d2-8213-5d3bb7d2571c createdAt: '2026-04-16T18:00:00Z' securitySchemes: APIKeyHeader: type: apiKey name: Authorization in: header ````