openapi: 3.1.0
info:
  title: Opik REST Prompts API
  description: "The Opik REST API is currently in beta and subject to change. If you have any questions or feedback about the APIs, please reach out on GitHub: https://github.com/comet-ml/opik.\n\nAll of the methods listed in this documentation are used by either the SDK or the UI to interact with the Opik server. As a result,\nthe methods have been optimized for these use-cases in mind. If you are looking for a method that is not listed above, please create\nand issue on GitHub or raise a PR!\n\nOpik includes two main deployment options that results in slightly different API usage:\n\n- **Self-hosted Opik instance:** You will simply need to specify the URL as `http://localhost:5173/api/<endpoint_path>` or similar. This is the default option for the docs.\n- **Opik Cloud:** You will need to specify the Opik API Key and Opik Workspace in the header. The format of the header should be:\n\n  ```\n  {\n    \"Comet-Workspace\": \"your-workspace-name\",\n    \"authorization\": \"your-api-key\"\n  }\n  ```\n\n  The full payload would therefore look like:\n  \n  ```\n  curl -X GET 'https://www.comet.com/opik/api/v1/private/projects' \\\n  -H 'Accept: application/json' \\\n  -H 'Comet-Workspace: <your-workspace-name>' \\\n  -H 'authorization: <your-api-key>'\n  ```\n\n  Do take note here that the authorization header value does not include the `Bearer ` prefix. To switch to using the Opik Cloud in the documentation, you can\n  click on the edit button displayed when hovering over the `Base URL` displayed on the right hand side of the docs.\n"
  contact:
    name: Github Repository
    url: https://github.com/comet-ml/opik
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: http://localhost:5173/api
  description: Local server
- url: https://www.comet.com/opik/api
  description: Opik Cloud
tags:
- name: Prompts
  description: Prompt resources
paths:
  /v1/private/prompts:
    get:
      tags:
      - Prompts
      summary: Get prompts
      description: Get prompts
      operationId: getPrompts
      parameters:
      - name: page
        in: query
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: size
        in: query
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: name
        in: query
        schema:
          type: string
          description: Filter prompts by name (partial match, case insensitive)
      - name: project_id
        in: query
        schema:
          type: string
          format: uuid
      - name: sorting
        in: query
        schema:
          type: string
      - name: filters
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptPage_Public'
    post:
      tags:
      - Prompts
      summary: Create prompt
      description: Create prompt
      operationId: createPrompt
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Prompt_Write'
      responses:
        '201':
          description: Created
          headers:
            Location:
              required: true
              style: simple
              schema:
                type: string
              example: ${basePath}/v1/private/prompts/{promptId}
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /v1/private/prompts/versions:
    post:
      tags:
      - Prompts
      summary: Create prompt version
      description: Create prompt version
      operationId: createPromptVersion
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromptVersion_Detail'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptVersion_Detail'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
    patch:
      tags:
      - Prompts
      summary: Update prompt versions
      description: 'Update one or more prompt versions.


        Note: Prompt versions are immutable by design.

        Only organizational properties, such as tags etc., can be updated.

        Core properties like template and metadata cannot be modified after creation.


        PATCH semantics:

        - non-empty values update the field

        - null values preserve existing field values (no change)

        - empty values explicitly clear the field

        '
      operationId: updatePromptVersions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptVersionBatchUpdate'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /v1/private/prompts/{id}:
    get:
      tags:
      - Prompts
      summary: Get prompt by id
      description: Get prompt by id; when mask_id or environment is provided, requestedVersion is populated with the resolved version. mask_id and environment are mutually exclusive.
      operationId: getPromptById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: mask_id
        in: query
        description: Optional mask version id; when set, requestedVersion is the mask row for that id
        schema:
          type: string
          format: uuid
      - name: environment
        in: query
        description: Optional environment name; when set, requestedVersion is the version mapped to that environment for the prompt
        schema:
          maxLength: 150
          minLength: 0
          pattern: ^[A-Za-z0-9_-]+$
          type: string
      responses:
        '200':
          description: Prompt resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
    put:
      tags:
      - Prompts
      summary: Update prompt
      description: Update prompt
      operationId: updatePrompt
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Prompt_Updatable'
      responses:
        '204':
          description: No content
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    delete:
      tags:
      - Prompts
      summary: Delete prompt
      description: Delete prompt
      operationId: deletePrompt
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No content
  /v1/private/prompts/delete:
    post:
      tags:
      - Prompts
      summary: Delete prompts
      description: Delete prompts batch
      operationId: deletePromptsBatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchDelete'
      responses:
        '204':
          description: No Content
  /v1/private/prompts/by-commit/{commit}:
    get:
      tags:
      - Prompts
      summary: Get prompt by commit
      description: Get prompt by commit
      operationId: getPromptByCommit
      parameters:
      - name: commit
        in: path
        required: true
        schema:
          pattern: ^[a-zA-Z0-9]{8}$
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
  /v1/private/prompts/versions/{versionId}:
    get:
      tags:
      - Prompts
      summary: Get prompt version by id
      description: Get prompt version by id
      operationId: getPromptVersionById
      parameters:
      - name: versionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Prompt version resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptVersion_Detail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
  /v1/private/prompts/{promptId}/versions/by-number/{versionNumber}:
    get:
      tags:
      - Prompts
      summary: Get prompt version by sequential number
      description: Get a prompt version by its sequential v<N> number for the given prompt.
      operationId: getPromptVersionByNumber
      parameters:
      - name: promptId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: versionNumber
        in: path
        required: true
        schema:
          maxLength: 10
          minLength: 0
          pattern: v\d+
          type: string
      responses:
        '200':
          description: Prompt version resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptVersion_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
  /v1/private/prompts/{id}/versions:
    get:
      tags:
      - Prompts
      summary: Get prompt versions
      description: Get prompt versions
      operationId: getPromptVersions
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: size
        in: query
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: search
        in: query
        description: Search text to find in template or change description fields
        schema:
          type: string
      - name: sorting
        in: query
        schema:
          type: string
      - name: filters
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptVersionPage_Public'
  /v1/private/prompts/retrieve-by-commits:
    post:
      tags:
      - Prompts
      summary: Get prompts by commits
      description: Get prompts by prompt version commits
      operationId: getPromptsByCommits
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptVersionCommitsRequest_Public'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromptVersionLink_Public'
  /v1/private/prompts/{promptId}/versions/{versionId}/restore:
    post:
      tags:
      - Prompts
      summary: Restore prompt version
      description: Restore a prompt version by creating a new version with the content from the specified version
      operationId: restorePromptVersion
      parameters:
      - name: promptId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: versionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptVersion_Detail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
  /v1/private/prompts/versions/retrieve:
    post:
      tags:
      - Prompts
      summary: Retrieve prompt version
      description: Retrieve prompt version
      operationId: retrievePromptVersion
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptVersionRetrieve_Detail'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptVersion_Detail'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
  /v1/private/prompts/versions/retrieve-by-ids:
    post:
      tags:
      - Prompts
      summary: Retrieve prompt versions by ids
      description: Retrieve a batch of prompt versions by their ids. Typically used by the UI to resolve mask overlays.
      operationId: retrievePromptVersionsByIds
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptVersionIdsRequest_Detail'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromptVersion_Detail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_Detail'
  /v1/private/prompts/versions/{versionId}/environments:
    patch:
      tags:
      - Prompts
      summary: Set prompt version environment
      description: 'Set or clear the environment owned by a prompt version.

        Setting a non-null environment moves ownership atomically: any previous owner of that

        environment for the same prompt has its environment cleared in the same transaction.

        Setting null clears the environment from the version.

        The environment must already exist in the workspace registry; unknown names return 404.

        '
      operationId: setPromptVersionEnvironment
      parameters:
      - name: versionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptVersionEnvironmentUpdate'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    PromptVersionIdsRequest_Detail:
      required:
      - ids
      type: object
      properties:
        ids:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
    JsonNode_Public:
      type: object
    PromptVersionLink_Public:
      type: object
      properties:
        prompt_version_id:
          type: string
          format: uuid
        commit:
          type: string
        prompt_id:
          type: string
          format: uuid
        prompt_name:
          type: string
    PromptVersion_Public:
      required:
      - template
      type: object
      properties:
        id:
          type: string
          description: version unique identifier, generated if absent
          format: uuid
        prompt_id:
          type: string
          format: uuid
          readOnly: true
        commit:
          pattern: ^[a-zA-Z0-9]{8}$
          type: string
          description: version short unique identifier, generated if absent. it must be 8 characters long
        version_number:
          type: string
          description: sequential version number in the format v<N>; null for masks
          readOnly: true
        template:
          minLength: 1
          type: string
        metadata:
          $ref: '#/components/schemas/JsonNode_Public'
        type:
          type: string
          enum:
          - mustache
          - jinja2
          - python
        version_type:
          type: string
          description: version type discriminator; defaults to prompt_version
          enum:
          - prompt_version
          - mask
        environment:
          maxLength: 150
          minLength: 0
          pattern: ^[A-Za-z0-9_-]+$
          type: string
          description: 'Deprecated: use ''environments'' instead'
          deprecated: true
        environments:
          maxItems: 100
          minItems: 0
          uniqueItems: true
          type: array
          items:
            maxLength: 150
            minLength: 0
            pattern: ^[A-Za-z0-9_-]+$
            type: string
        change_description:
          type: string
        tags:
          uniqueItems: true
          type: array
          items:
            minLength: 1
            type: string
        template_structure:
          type: string
          readOnly: true
          enum:
          - text
          - chat
        created_at:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: string
          readOnly: true
    JsonNode_Write:
      type: object
    ErrorMessage_Detail:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    BatchDelete:
      required:
      - ids
      type: object
      properties:
        ids:
          maxItems: 1000
          minItems: 1
          uniqueItems: true
          type: array
          items:
            type: string
            format: uuid
    PromptPage_Public:
      type: object
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int64
        content:
          type: array
          items:
            $ref: '#/components/schemas/Prompt_Public'
        sortableBy:
          type: array
          items:
            type: string
    Prompt_Public:
      required:
      - name
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          minLength: 1
          type: string
        project_id:
          type: string
          description: Project ID. Takes precedence over project_name when both are provided.
          format: uuid
        description:
          maxLength: 255
          minLength: 0
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
        template_structure:
          type: string
          description: 'Template structure type: ''text'' or ''chat''. Immutable after creation.'
          default: text
          enum:
          - text
          - chat
        tags:
          uniqueItems: true
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: string
          readOnly: true
        last_updated_at:
          type: string
          format: date-time
          readOnly: true
        last_updated_by:
          type: string
          readOnly: true
        version_count:
          type: integer
          format: int64
          readOnly: true
    PromptVersionCommitsRequest_Public:
      required:
      - commits
      type: object
      properties:
        commits:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            minLength: 1
            type: string
    Prompt_Updatable:
      required:
      - name
      type: object
      properties:
        name:
          minLength: 1
          type: string
        description:
          maxLength: 255
          minLength: 0
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
        tags:
          uniqueItems: true
          type: array
          items:
            type: string
    Prompt_Write:
      required:
      - name
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          minLength: 1
          type: string
        project_id:
          type: string
          description: Project ID. Takes precedence over project_name when both are provided.
          format: uuid
        project_name:
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
          description: For project scope, specify either project_id or project_name. If project_name is provided and the project does not exist, it will be created. Ignored when project_id is provided. If neither is provided, the prompt is created at workspace level.
        description:
          maxLength: 255
          minLength: 0
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
        template:
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
        metadata:
          $ref: '#/components/schemas/JsonNode_Write'
        change_description:
          type: string
        type:
          type: string
          enum:
          - mustache
          - jinja2
          - python
        template_structure:
          type: string
          description: 'Template structure type: ''text'' or ''chat''. Immutable after creation.'
          default: text
          enum:
          - text
          - chat
        tags:
          uniqueItems: true
          type: array
          items:
            type: string
    JsonNode_Detail:
      type: object
    PromptVersion_Detail:
      required:
      - template
      type: object
      properties:
        id:
          type: string
          description: version unique identifier, generated if absent
          format: uuid
        prompt_id:
          type: string
          format: uuid
          readOnly: true
        commit:
          pattern: ^[a-zA-Z0-9]{8}$
          type: string
          description: version short unique identifier, generated if absent. it must be 8 characters long
        version_number:
          type: string
          description: sequential version number in the format v<N>; null for masks
          readOnly: true
        template:
          minLength: 1
          type: string
        metadata:
          $ref: '#/components/schemas/JsonNode_Detail'
        type:
          type: string
          enum:
          - mustache
          - jinja2
          - python
        version_type:
          type: string
          description: version type discriminator; defaults to prompt_version
          enum:
          - prompt_version
          - mask
        environment:
          maxLength: 150
          minLength: 0
          pattern: ^[A-Za-z0-9_-]+$
          type: string
          description: 'Deprecated: use ''environments'' instead'
          deprecated: true
        environments:
          maxItems: 100
          minItems: 0
          uniqueItems: true
          type: array
          items:
            maxLength: 150
            minLength: 0
            pattern: ^[A-Za-z0-9_-]+$
            type: string
        change_description:
          type: string
        tags:
          uniqueItems: true
          type: array
          items:
            minLength: 1
            type: string
        variables:
          uniqueItems: true
          type: array
          readOnly: true
          items:
            type: string
            readOnly: true
        template_structure:
          type: string
          readOnly: true
          enum:
          - text
          - chat
        created_at:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: string
          readOnly: true
    PromptVersionBatchUpdate:
      required:
      - ids
      - update
      type: object
      properties:
        ids:
          maxItems: 1000
          minItems: 1
          uniqueItems: true
          type: array
          description: IDs of prompt versions to update
          items:
            type: string
            description: IDs of prompt versions to update
            format: uuid
        update:
          $ref: '#/components/schemas/PromptVersionUpdate'
        merge_tags:
          type: boolean
          description: 'Tag merge behavior:

            - true: Add new tags to existing tags (union)

            - false: Replace all existing tags with new tags (default behaviour if not provided)

            '
          default: false
      description: 'Request to update one or more prompt versions.

        Note: Prompt versions are immutable by design - only organizational properties (such as tags etc.) can be updated.

        '
    Prompt_Detail:
      required:
      - name
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          minLength: 1
          type: string
        project_id:
          type: string
          description: Project ID. Takes precedence over project_name when both are provided.
          format: uuid
        description:
          maxLength: 255
          minLength: 0
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
        template_structure:
          type: string
          description: 'Template structure type: ''text'' or ''chat''. Immutable after creation.'
          default: text
          enum:
          - text
          - chat
        tags:
          uniqueItems: true
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: string
          readOnly: true
        last_updated_at:
          type: string
          format: date-time
          readOnly: true
        last_updated_by:
          type: string
          readOnly: true
        version_count:
          type: integer
          format: int64
          readOnly: true
        latest_version:
          $ref: '#/components/schemas/PromptVersion_Detail'
        requested_version:
          $ref: '#/components/schemas/PromptVersion_Detail'
    PromptVersionEnvironmentUpdate:
      required:
      - environments
      type: object
      properties:
        environments:
          maxItems: 100
          minItems: 0
          uniqueItems: true
          type: array
          items:
            maxLength: 150
            minLength: 0
            pattern: ^[A-Za-z0-9_-]+$
            type: string
      description: 'Replace the full set of environments assigned to a prompt version.

        The provided set becomes the new complete set of environments for this version.

        - Non-empty set: assigns each environment to this version; if another version of the same prompt currently owns any of those environments, ownership is moved atomically.

        - Empty set: clears all environments from this version.

        All environments must already exist in the workspace registry; unknown names return 404.

        '
    PromptVersionPage_Public:
      type: object
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        total:
          type: integer
          format: int64
        content:
          type: array
          items:
            $ref: '#/components/schemas/PromptVersion_Public'
        sortableBy:
          type: array
          items:
            type: string
    CreatePromptVersion_Detail:
      required:
      - name
      - version
      type: object
      properties:
        name:
          minLength: 1
          type: string
        version:
          $ref: '#/components/schemas/PromptVersion_Detail'
        template_structure:
          type: string
          description: 'Template structure for the prompt: ''text'' or ''chat''. Note: This field is only used when creating a new prompt. If a prompt with the given name already exists, this field is ignored and the existing prompt''s template structure is used. Template structure is immutable after prompt creation.'
          default: text
          enum:
          - text
          - chat
        project_id:
          type: string
          description: Project ID. Takes precedence over project_name when both are provided.
          format: uuid
        project_name:
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
          description: If provided, scopes the prompt to the specified project. Ignored when project_id is provided.
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: string
    PromptVersionUpdate:
      type: object
      properties:
        tags:
          maxItems: 50
          minItems: 0
          uniqueItems: true
          type: array
          description: 'Tags to set or merge with existing tags. Follows PATCH semantics:

            - If merge_tags is true, these tags will be added to existing tags.

            - If merge_tags is false, these tags will replace all existing tags.

            - null: preserve existing tags (no change).

            - empty set: clear all tags when merge_tags is false.

            '
          items:
            maxLength: 100
            minLength: 0
            type: string
            description: 'Tags to set or merge with existing tags. Follows PATCH semantics:

              - If merge_tags is true, these tags will be added to existing tags.

              - If merge_tags is false, these tags will replace all existing tags.

              - null: preserve existing tags (no change).

              - empty set: clear all tags when merge_tags is false.

              '
      description: 'Update to apply to prompt versions.

        Note: Prompt versions are immutable by design.

        Only organizational properties (such as tags etc.) can be updated.

        Core properties like template, metadata etc. cannot be modified after creation.

        '
    PromptVersionRetrieve_Detail:
      required:
      - name
      type: object
      properties:
        name:
          minLength: 1
          type: string
        commit:
          type: string
        environment:
          maxLength: 150
          minLength: 0
          pattern: ^[A-Za-z0-9_-]+$
          type: string
          description: If provided, resolves to the version mapped to this environment for the prompt; mutually exclusive with commit and version_number
        version_number:
          maxLength: 10
          minLength: 0
          pattern: v\d+
          type: string
          description: If provided, resolves to the version with this sequential number (e.g. v3); mutually exclusive with commit and environment
        project_name:
          pattern: (?s)^\s*(\S.*\S|\S)\s*$
          type: string
          description: If provided, scopes the search to the specified project