# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Showpad Divisions API
  version: 1.0.0
extends: openapi/showpad-divisions-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: 24
- target: $.paths['/divisions.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List divisions with filters (v3)
      effect: read
      questions:
      - Which divisions have asset sharing enabled, using the older v3 list?
      - Can I filter the v3 division list by name or external ID?
      instructions:
      - text: List v3 divisions named {name}.
        slots:
          name: query.name
      - text: Show v3 divisions where asset sharing is {hasDivisionAssetSharingEnabled}.
        slots:
          hasDivisionAssetSharingEnabled: query.hasDivisionAssetSharingEnabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a division
      effect: write
      questions:
      - How do I set up a new division for another business unit?
      - Can I turn on division asset sharing when creating a division?
      instructions:
      - text: Create a division called {name}.
        slots:
          name: requestBody.name
      - text: Create division {name} with external ID {externalId}.
        slots:
          name: requestBody.name
          externalId: requestBody.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count divisions
      effect: read
      questions:
      - How many divisions exist in our account?
      - What number of divisions share assets with others?
      instructions:
      - text: Count all divisions.
      - text: Count divisions named {name}.
        slots:
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/description.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the Division model and its APIs
      effect: read
      questions:
      - What fields make up the Division model?
      - Which division endpoints are available according to the self-description?
      instructions:
      - text: Show the Division model description.
      - text: Fetch the division resource metadata and available APIs.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id1}/usergroups/{id2}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Link or unlink a division and group via GET
      effect: write
      questions:
      - Is there a GET call that links or unlinks a division and a user group depending on a method value?
      - Can I switch a group's division membership with one method parameter?
      instructions:
      - text: Use method {method} to link or unlink division {id1} and user group {id2} with the combined GET call.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      - text: Run the method-switched division-group call {method} for division {id1} and group {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id1}/usergroups/{id2}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a user group to a division
      effect: write
      questions:
      - How do I give an existing user group access to a division?
      - Can I link a group to a division using both IDs?
      instructions:
      - text: Link division {id1} to user group {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Add existing group {id2} into division {id1}.
        slots:
          id2: path.id2
          id1: path.id1
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id1}/usergroups/{id2}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a user group from a division
      effect: destructive
      questions:
      - How do I take a user group out of a division?
      - Can I revoke a group's division access without deleting the group?
      instructions:
      - text: Unlink user group {id2} from division {id1}.
        slots:
          id2: path.id2
          id1: path.id1
      - text: Remove division {id1}'s association with group {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a division (v3)
      effect: read
      questions:
      - How do I fetch one division's record with the older v3 endpoint?
      - Can I expand related data when reading a division in v3?
      instructions:
      - text: Get division {id} from the v3 endpoint.
        slots:
          id: path.id
      - text: Fetch v3 division {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a division with PUT
      effect: write
      questions:
      - How do I rename a division with a PUT request?
      - Can I toggle division asset sharing via PUT?
      instructions:
      - text: PUT a new name {name} on division {id}.
        slots:
          name: requestBody.name
          id: path.id
      - text: Using PUT, set asset sharing to {hasDivisionAssetSharingEnabled} for division {id}.
        slots:
          hasDivisionAssetSharingEnabled: requestBody.hasDivisionAssetSharingEnabled
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a division with POST
      effect: write
      questions:
      - Is there a POST alternative for editing a division when PUT isn't allowed?
      - Can I change a division's external ID through a POST update?
      instructions:
      - text: Via the POST update call, set division {id}'s external ID to {externalId}.
        slots:
          id: path.id
          externalId: requestBody.externalId
      - text: POST a rename of division {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a division
      effect: destructive
      questions:
      - How do I permanently remove a division?
      - What call deletes a division by its ID?
      instructions:
      - text: Delete division {id}.
        slots:
          id: path.id
      - text: Remove the division with ID {id} from the account.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/assets.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a division's assets
      effect: read
      questions:
      - What content assets live in a given division?
      - Can I list only the downloadable or shareable assets of a division?
      - Which files of a certain type are in this division?
      instructions:
      - text: List assets in division {id}.
        slots:
          id: path.id
      - text: Show division {id} assets with file type {filetype}.
        slots:
          id: path.id
          filetype: query.filetype
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/assets.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an asset to a division
      effect: write
      questions:
      - How do I upload a new file into a division's library?
      - Can I mark an asset as sensitive or non-downloadable when adding it to a division?
      instructions:
      - text: Upload {file} as an asset named {name} to division {id}.
        slots:
          file: requestBody.file
          name: requestBody.name
          id: path.id
      - text: Add a URL asset {url} to division {id} that expires {expiresAt}.
        slots:
          url: requestBody.url
          id: path.id
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/comments.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments in a division
      effect: read
      questions:
      - What comments have been posted within a division?
      - Can I page through a division's comments sorted by date?
      instructions:
      - text: List comments for division {id}.
        slots:
          id: path.id
      - text: Show {limit} comments from division {id} sorted by {sort}.
        slots:
          limit: query.limit
          id: path.id
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a division to a user group via Link body
      effect: write
      questions:
      - How do I attach a user group to a division using a Link reference?
      - Is there a generic link endpoint on a division record?
      instructions:
      - text: Link division {id} to the user group referenced by {Link}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Attach {Link} to division record {id}.
        slots:
          Link: requestBody.Link
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/tags.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a division's tags
      effect: read
      questions:
      - What tags are defined in a particular division?
      - Can I list only unfinished or customer-type tags in a division?
      instructions:
      - text: List tags in division {id}.
        slots:
          id: path.id
      - text: Show division {id} tags with status {status}.
        slots:
          id: path.id
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/tags.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a tag to a division
      effect: write
      questions:
      - How do I create a new tag inside a division?
      - Which values do I need to add a tag to a division?
      instructions:
      - text: Add a tag of type {type} to division {id} with divisionId {divisionId}.
        slots:
          type: requestBody.type
          id: path.id
          divisionId: requestBody.divisionId
      - text: Create a {type} tag in division {divisionId} through division {id}.
        slots:
          type: requestBody.type
          divisionId: requestBody.divisionId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/tickets.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a division's tickets
      effect: read
      questions:
      - Which tickets belong to a given division?
      - Can I filter a division's tickets to synced ones only?
      instructions:
      - text: List tickets for division {id}.
        slots:
          id: path.id
      - text: Show division {id} tickets where isSynced is {isSynced}.
        slots:
          id: path.id
          isSynced: query.isSynced
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink a resource from a division
      effect: destructive
      questions:
      - How do I detach a linked user group from a division with a Link reference?
      - Can I remove a Link association from a division without deleting it?
      instructions:
      - text: Unlink {Link} from division {id}.
        slots:
          Link: requestBody.Link
          id: path.id
      - text: Detach linked resource {Link} from division record {id}.
        slots:
          Link: requestBody.Link
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/usergroups.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a division's user groups
      effect: read
      questions:
      - Which user groups are part of a given division?
      - Can I page through a division's groups?
      instructions:
      - text: List user groups in division {id}.
        slots:
          id: path.id
      - text: Show {limit} groups of division {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/usergroups.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a group to a division
      effect: write
      questions:
      - How do I add a new group entry to a division?
      - What details must I send when adding a group to a division?
      instructions:
      - text: Add a group to division {id} for {firstName} {lastName} ({email}), username {userName}, language {language}, active {isActive}.
        slots:
          id: path.id
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
          userName: requestBody.userName
          language: requestBody.language
          isActive: requestBody.isActive
      - text: Create a division {id} group entry using email {email}.
        slots:
          id: path.id
          email: requestBody.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{id}/users.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a division's users
      effect: read
      questions:
      - Who are the users in a particular division?
      - Can I see only division users created since a certain date?
      instructions:
      - text: List users in division {id}.
        slots:
          id: path.id
      - text: Show division {id} users created since {createdSince}.
        slots:
          id: path.id
          createdSince: query.createdSince
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions'].get
  update:
    x-apievangelist-phrasing:
      intent: List divisions (v4)
      effect: read
      questions:
      - What's the v4 way to list all divisions in Showpad?
      - How do I page through divisions with the newer API?
      instructions:
      - text: Using v4, list all divisions.
      - text: Get {limit} v4 divisions starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/divisions/{divisionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a division (v4)
      effect: read
      questions:
      - How do I get one division's details with the v4 API?
      - What does the v4 division object contain?
      instructions:
      - text: Retrieve v4 division {divisionId}.
        slots:
          divisionId: path.divisionId
      - text: Get the details of division {divisionId} from the v4 endpoint.
        slots:
          divisionId: path.divisionId
      method: generated
      generated: '2026-10-01'