Coactive dynamicTags API

openapi: 3.1.0
info:
  title: API Reference agentic-search > agenticSearch dynamicTags API
  version: 1.0.0
servers:
- url: https://api.coactive.ai
  description: Production
- url: https://app.coactive.ai
  description: Production
tags:
- name: dynamicTags
paths:
  /api/v3/dynamic-tags/groups:
    get:
      operationId: list-groups
      summary: Retrieve a paginated list of groups
      description: Retrieves a paginated list of dynamic tag groups. Supports filtering by name, version name, or status.
      tags:
      - dynamicTags
      parameters:
      - name: name
        in: query
        description: Filter by group name
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: name_contains
        in: query
        description: Filter by group name containing this string
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: version_name
        in: query
        description: Filter by version name
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: group_status
        in: query
        description: Filter by status
        required: false
        schema:
          oneOf:
          - $ref: '#/components/schemas/DynamicTagGroupVersionStatus'
          - type: 'null'
      - name: group_ids
        in: query
        description: Filter by group IDs
        required: false
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
      - name: visual_encoder
        in: query
        description: Filter by visual encoder
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: transcript_encoder
        in: query
        description: Filter by transcript encoder
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: exclude_group_ids
        in: query
        description: Exclude groups with these IDs
        required: false
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
      - name: is_shareable
        in: query
        description: Whether to return only shareable groups
        required: false
        schema:
          type: boolean
          default: false
      - name: created_user_id
        in: query
        description: Filter by user who created the group
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: created_dt_from
        in: query
        description: Filter groups created on or after this date
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - name: created_dt_to
        in: query
        description: Filter groups created before this date
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - name: training_dataset_id
        in: query
        description: Filter by associated training dataset ID
        required: false
        schema:
          type:
          - string
          - 'null'
          format: uuid
      - name: page
        in: query
        description: Page number (1-indexed)
        required: false
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of items per page
        required: false
        schema:
          type: integer
          default: 25
      - name: sort_field
        in: query
        description: Field to sort by
        required: false
        schema:
          type: string
          default: name
      - name: sort_direction
        in: query
        description: Sort direction
        required: false
        schema:
          $ref: '#/components/schemas/DynamicTagSortDirection'
      - name: include_training_datasets
        in: query
        description: Include at most 10 associated datasets in the response
        required: false
        schema:
          type: boolean
          default: false
      - name: include_versions
        in: query
        description: Include the latest draft and published versions of the group in the response
        required: false
        schema:
          type: boolean
          default: false
      - name: include_tags
        in: query
        description: Include at most 10 tag names in the response
        required: false
        schema:
          type: boolean
          default: false
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicTagGetGroupsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DynamicTagGroupVersionStatus:
      type: string
      enum:
      - creating
      - updating
      - draft
      - unpublished_changes
      - published
      - validated
      - superseded
      - error
      - deleting
      - deleted
      description: Status of a group version.
      title: DynamicTagGroupVersionStatus
    DynamicTagPagedMetaResponse:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/DynamicTagPagedPageDetailsResponse'
          description: Details about pagination
        has_next_page:
          type: boolean
          default: false
          description: Whether another page exists
      required:
      - page
      description: Metadata about the paginated response.
      title: DynamicTagPagedMetaResponse
    DynamicTagGroupVersionResponse:
      type: object
      properties:
        group_id:
          type: string
          format: uuid
          description: Unique identifier for the group
        group_version_id:
          type: string
          format: uuid
          description: Version identifier
        name:
          type: string
          description: Name of the group
        version_name:
          type:
          - string
          - 'null'
          description: Human-readable version name
        status:
          $ref: '#/components/schemas/DynamicTagGroupVersionStatus'
          description: Current status of the group version
        shareable:
          type: boolean
          description: Whether the group can be shared across datasets
        created_user_id:
          type: string
          description: ID of the user who created this version
        updated_user_id:
          type: string
          description: ID of the user who last updated this version
        created_dt:
          type: string
          format: date-time
          description: Timestamp when the version was created
        updated_dt:
          type: string
          format: date-time
          description: Timestamp when the version was last updated
        group_created_user_id:
          type: string
          description: ID of the user who created this group
        group_created_dt:
          type: string
          format: date-time
          description: Timestamp when the group was created
        group_description:
          type:
          - string
          - 'null'
          description: Human-readable description of the group
        tags_preview:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DynamicTagTagVersionSummary'
          description: The first 10 tags associated with the group version
        tags_count:
          type:
          - integer
          - 'null'
          description: Total number of tags associated with the group version
        all_draft_tags_reviewed_dt:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when all draft tags were reviewed
        review_tags_visited_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when a user first visited the Review Tags section for this group version
        training_datasets:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DynamicTagDataset'
          description: List of training datasets associated with the group version
      required:
      - group_id
      - group_version_id
      - name
      - status
      - shareable
      - created_user_id
      - updated_user_id
      - created_dt
      - updated_dt
      - group_created_user_id
      - group_created_dt
      - tags_preview
      - tags_count
      - all_draft_tags_reviewed_dt
      - review_tags_visited_at
      description: Response model for a group version.
      title: DynamicTagGroupVersionResponse
    DynamicTagTagVersionStatus:
      type: string
      enum:
      - creating
      - updating
      - draft
      - unpublished_changes
      - published
      - error
      - deleting
      - deleted
      description: Status of a tag version.
      title: DynamicTagTagVersionStatus
    ValidationErrorLocItems:
      oneOf:
      - type: string
      - type: integer
      - type: string
      - type: integer
      title: ValidationErrorLocItems
    DynamicTagSortDirection:
      type: string
      enum:
      - asc
      - desc
      description: Sort direction.
      title: DynamicTagSortDirection
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      title: HTTPValidationError
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DynamicTagTagVersionSummary:
      type: object
      properties:
        tag_id:
          type: string
          format: uuid
          description: Unique identifier for the tag
        tag_version_id:
          type: string
          format: uuid
          description: Unique identifier for the tag version
        name:
          type: string
          description: Name of the tag
        status:
          $ref: '#/components/schemas/DynamicTagTagVersionStatus'
          description: Status of the tag
      required:
      - tag_id
      - tag_version_id
      - name
      - status
      description: Response model for a tag with its current version.
      title: DynamicTagTagVersionSummary
    DynamicTagPagedPageDetailsResponse:
      type: object
      properties:
        page:
          type: integer
          description: Current page number (1-indexed)
        per_page:
          type: integer
          description: Number of items per page
      required:
      - page
      - per_page
      description: Pagination metadata.
      title: DynamicTagPagedPageDetailsResponse
    DynamicTagSortField:
      type: object
      properties:
        field:
          type: string
          description: Field name to sort by
        direction:
          $ref: '#/components/schemas/DynamicTagSortDirection'
          description: Sort direction
      required:
      - field
      description: Sort field details.
      title: DynamicTagSortField
    DynamicTagGroupDatasetAssociationStatus:
      type: string
      enum:
      - unscored
      - queued
      - scoring
      - scored
      - error
      - deleting
      - deleted
      description: Status of association between group and dataset.
      title: DynamicTagGroupDatasetAssociationStatus
    DynamicTagDataset:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Dataset identifier
        status:
          $ref: '#/components/schemas/DynamicTagGroupDatasetAssociationStatus'
          description: Dataset status
      required:
      - id
      - status
      description: Summary information about associated datasets.
      title: DynamicTagDataset
    DynamicTagGetGroupsResponse:
      type: object
      properties:
        meta:
          oneOf:
          - $ref: '#/components/schemas/DynamicTagPagedMetaResponse'
          - type: 'null'
          description: Metadata for pagination
        data:
          type: array
          items:
            $ref: '#/components/schemas/DynamicTagGroupVersionResponse'
          description: The paginated data
        sort:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DynamicTagSortField'
          description: Sort details
      required:
      - data
      description: Response model for retrieving a paginated list of groups.
      title: DynamicTagGetGroupsResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer