# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for cdp-api Folders API
  version: 1.0.0
extends: openapi/treasure-data-folders-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/audiences/{audienceId}/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment folder in a parent segment
      effect: write
      questions:
      - Can I organize segments into a new folder under a parent segment?
      - What does a new segment folder need besides a name?
      instructions:
      - text: Create segment folder {name} described as {description} in parent segment {audienceId}.
        slots:
          name: requestBody.name
          description: requestBody.description
          audienceId: path.audienceId
      - text: Add a folder {name} with description {description} to audience {audienceId}.
        slots:
          name: requestBody.name
          description: requestBody.description
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/folders/{folderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment folder in a parent segment
      effect: read
      questions:
      - Can I look up one segment folder within a parent segment?
      - What name and description does a given segment folder have?
      instructions:
      - text: Show segment folder {folderId} in parent segment {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      - text: Get folder {folderId} of audience {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/folders/{folderId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment folder (legacy)
      effect: destructive
      questions:
      - Can I delete a segment folder in legacy Audience Studio?
      - What removes a folder from a parent segment in the legacy studio?
      instructions:
      - text: Delete segment folder {folderId} from parent segment {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      - text: Remove legacy folder {folderId} in audience {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/folders/{folderId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a segment folder (legacy)
      effect: write
      questions:
      - Can I rename a segment folder in legacy Audience Studio?
      - Is it possible to change a legacy folder's description?
      instructions:
      - text: Rename segment folder {folderId} in parent segment {audienceId} to {name}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
          name: requestBody.name
      - text: Set the description of legacy folder {folderId} in audience {audienceId} to {description}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/folders/{folderId}/put_in'].post
  update:
    x-apievangelist-phrasing:
      intent: Move segments into a folder (legacy)
      effect: write
      questions:
      - Can I move existing segments into a folder in legacy Audience Studio?
      - What files segments under a different folder in the legacy studio?
      instructions:
      - text: Move segments into folder {folderId} of parent segment {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      - text: Put segments into legacy folder {folderId} in audience {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/by-folder/{folderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List everything under a folder
      effect: read
      questions:
      - What segments, funnels, models and tokens live under a folder?
      - Can I control how deep into child folders the listing goes, and include segment rules?
      instructions:
      - text: List objects under folder {folderId} to depth {depth}.
        slots:
          folderId: path.folderId
          depth: query.depth
      - text: List contents of folder {folderId} to depth {depth} with rules {with_rule}.
        slots:
          folderId: path.folderId
          depth: query.depth
          with_rule: query.with_rule
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a folder via the entities API
      effect: write
      questions:
      - Can I create a folder in the current Audience Studio through the entities API?
      - What attributes define a new folder entity?
      instructions:
      - text: Create an entities-API folder with attributes {attributes}.
        slots:
          attributes: requestBody.attributes
      - text: Create a folder entity with attributes {attributes} under {relationships}.
        slots:
          attributes: requestBody.attributes
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/folders/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a folder by entity ID
      effect: read
      questions:
      - Can I fetch a folder using only its entity ID?
      - What does the entities API return for one folder?
      instructions:
      - text: Get entities-API folder {id}.
        slots:
          id: path.id
      - text: Fetch folder entity {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/folders/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a folder via the entities API
      effect: destructive
      questions:
      - Can I delete a folder by its entity ID in the current Audience Studio?
      - What removes a folder entity?
      instructions:
      - text: Delete entities-API folder {id}.
        slots:
          id: path.id
      - text: Remove folder entity {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/folders/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a folder via the entities API
      effect: write
      questions:
      - Can I rename or move a folder entity by its ID?
      - Which folder attributes can the entities API change?
      instructions:
      - text: Patch entities-API folder {id} with attributes {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      - text: Move folder entity {id} under {relationships}.
        slots:
          id: path.id
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'