> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nvisy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List labels

> Returns the deployment's built-in label taxonomy: the categories of sensitive data (PII, PHI, PCI, ...) that policies can target.



## OpenAPI

````yaml /api-reference/openapi.json get /catalog/labels/
openapi: 3.1.0
info:
  title: Nvisy API
  summary: Document processing and annotation platform
  description: >-
    Nvisy provides intelligent document processing, annotation, and analysis
    capabilities. This API enables document upload, OCR processing, embedding
    generation, and semantic search across your document collections.
  termsOfService: https://nvisy.com/legal/terms-of-service
  contact:
    name: Nvisy Support
    url: https://nvisy.com
    email: hello@nvisy.com
  license:
    name: Proprietary
    url: https://nvisy.com/license
  version: 0.1.0
servers: []
security: []
tags:
  - name: Accounts
    description: Account management and profile operations
  - name: Authentication
    description: Login, signup, and token management
  - name: Workspaces
    description: Workspace creation and management
  - name: Files
    description: File upload, download, and management
  - name: Members
    description: Workspace member management
  - name: Invites
    description: Workspace invitation handling
  - name: API Tokens
    description: API token management
  - name: Connections
    description: External provider connections
  - name: Pipelines
    description: Redaction pipeline configuration
  - name: Pipeline Runs
    description: Pipeline run execution and review
  - name: Policies
    description: Redaction policy configuration
  - name: Webhooks
    description: Webhook configuration
  - name: Notifications
    description: Account notification management
  - name: Health
    description: Service health checks
paths:
  /catalog/labels/:
    get:
      tags:
        - Catalog
      summary: List labels
      description: >-
        Returns the deployment's built-in label taxonomy: the categories of
        sensitive data (PII, PHI, PCI, ...) that policies can target.
      responses:
        '200':
          description: |-
            Registry of [`Label`]s, keyed by id.

            Holds the authoritative definitions (localized names + descriptions)
            for a run.
            A [`LabelRef`] carried on a detection or entity is resolved back to
            its full [`Label`] with [`get`].

            [`get`]: LabelCatalog::get
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelCatalog'
        '401':
          description: >-
            HTTP error response representation with security-conscious design.


            This struct contains all the information needed to serialize an
            error

            response, including the error name, message, HTTP status code,
            resource

            information, and user-friendly messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    LabelCatalog:
      description: |-
        Registry of [`Label`]s, keyed by id.

        Holds the authoritative definitions (localized names + descriptions)
        for a run.
        A [`LabelRef`] carried on a detection or entity is resolved back to
        its full [`Label`] with [`get`].

        [`get`]: LabelCatalog::get
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Label'
    ErrorResponse:
      description: |-
        HTTP error response representation with security-conscious design.

        This struct contains all the information needed to serialize an error
        response, including the error name, message, HTTP status code, resource
        information, and user-friendly messages.
      type: object
      properties:
        message:
          description: User-friendly error message safe for client display
          type: string
        name:
          description: The error name/type identifier
          type: string
        resource:
          description: The resource that the error relates to (optional, set by handler)
          type: string
        suggestion:
          description: Helpful suggestion for resolving the error (optional)
          type: string
        validation:
          description: Validation error details for field-specific errors
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
      required:
        - name
        - message
    Label:
      description: >-
        Kind of sensitive information: a stable [`id`], per-language

        [`LabelLocale`]s, an optional [`category`], and zero or more tags.


        # Identity


        Labels are identified by [`id`] — a stable lowercase `snake_case`

        string (`"phone_number"`), never localized, and the catalog key that a

        [`LabelRef`] resolves through. Selectors match by id. Derived equality

        is *structural*: two labels with the same id but different

        localizations or tags are not `==`; compare [`id`] for identity.


        # Localization


        The display name and description are localized per [`LanguageTag`].

        English (`"en"`) is required at construction and is the fallback when a

        requested locale is absent, so [`localization`] always returns some

        text — NER and LLM read the analysis language's name and description to

        prompt the model, keyed by the stable id.


        # Category and tags


        [`category`] is the single coarse group a label belongs to (`financial`,

        `health`, `identity`, …), for organizing detected entities by kind.
        Built-in

        labels ship with one; a custom label has none unless set.


        [`tags`] is a free-form list of *cross-cutting* markers a policy
        selector

        matches against — sensitivity flags a label may carry several of (`pii`,

        `phi`, `pci`, `sad`, `secret`). Distinct from the category: a label has
        at

        most one category but any number of tags. Custom labels can ship with
        zero

        of either.


        [`id`]: Label::id

        [`localization`]: Label::localization

        [`category`]: Label::category

        [`tags`]: Label::tags
      type: object
      properties:
        category:
          $ref: '#/components/schemas/Category'
        id:
          type: string
        localizations:
          $ref: '#/components/schemas/LocalizedText'
        tags:
          type: array
          items:
            type: string
      required:
        - id
        - localizations
        - tags
    ValidationErrorDetail:
      description: Validation error details for field-specific errors.
      type: object
      properties:
        code:
          description: Error code for the validation failure
          type: string
        field:
          description: Field name that failed validation
          type: string
        message:
          description: Human-readable error message
          type: string
        params:
          description: Additional parameters related to the validation error
          type: object
          additionalProperties: true
      required:
        - field
        - code
        - message
    Category:
      description: >-
        The coarse group a [`Label`] belongs to, for organizing detected
        entities

        by kind (`financial`, `health`, `identity`, …).


        A category answers "what *sort* of information is this" at a display
        level:

        a consumer groups a redaction audit into sections by category. It is

        distinct from a label's [`tags`], which are cross-cutting sensitivity

        markers (`pii`, `phi`, `pci`) a label may carry several of; a label has
        at

        most **one** category. Built-in labels ship with a category; a custom

        [`Label`] has none unless one is set.


        The value is an open, lowercase `snake_case` identifier, so a custom
        label

        can define its own category rather than being confined to the shipped
        set.


        [`Label`]: super::Label

        [`tags`]: super::Label::tags
      type: string
    LocalizedText:
      description: |-
        A value localized per [`LanguageTag`], with an English-first fallback.

        The reusable mechanism behind any text that varies by language: a
        [`Label`]'s display name and description, a redaction operator's bucket
        label, and so on. English (`"en"`) is the conventional anchor —
        constructors seed it, and [`resolve`] falls back to it (then to any
        entry) when a requested locale is absent, so a caller that supplied
        English always gets *some* value.

        Generic over the stored value `T`, so it carries a bare `HipStr`
        (a bucket label) or a richer struct (a label's name-plus-description)
        equally. It is a thin wrapper over a `HashMap<LanguageTag, T>`; the
        added value is the fallback policy in [`resolve`], kept in one place
        rather than reimplemented at each use site.

        [`Label`]: crate::entity::Label
        [`resolve`]: LocalizedText::resolve
      type: object
      additionalProperties:
        $ref: '#/components/schemas/LabelLocale'
    LabelLocale:
      description: |-
        A label's human-facing text in one language: a display name and an
        optional fuller description.

        The `name` is a short, natural-language phrase (`"phone number"`) — the
        label a zero-shot NER model like GLiNER matches on, and the primary
        text an LLM prompt shows. The `description` is optional extra guidance
        for backends that consume it (GLiNER-2.0's bi-encoder, an LLM); leave
        it `None` when the name alone is clear.
      type: object
      properties:
        description:
          description: |-
            Optional fuller description, for description-capable backends
            (GLiNER-2.0, LLM). `None` when the name suffices.
          type: string
        name:
          description: |-
            Short natural-language display name (e.g. `"phone number"`). What a
            zero-shot NER model matches on and an LLM prompt surfaces.
          type: string
      required:
        - name

````