# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluence Cloud REST API v2 Space Roles API
  version: 1.0.0
extends: openapi/confluence-space-roles-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: 8
- target: $.paths['/space-roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the available space roles
      effect: read
      questions:
      - What space roles can I assign people in Confluence?
      - Can I filter space roles by type or by a principal who holds them?
      instructions:
      - text: List the available space roles.
      - text: Show the {role-type} space roles for space {space-id}.
        slots:
          role-type: query.role-type
          space-id: query.space-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/space-roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom space role
      effect: write
      questions:
      - How do I define a new space role with its own set of permissions?
      - Who is allowed to create a space role?
      instructions:
      - text: Create a space role named {name} described as {description} with permissions {spacePermissions}.
        slots:
          name: requestBody.name
          description: requestBody.description
          spacePermissions: requestBody.spacePermissions
      - text: Add a new role {name} granting {spacePermissions}, described {description}.
        slots:
          name: requestBody.name
          spacePermissions: requestBody.spacePermissions
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/space-roles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a space role by id
      effect: read
      questions:
      - What permissions does a particular space role include?
      - How do I fetch the details of one space role?
      instructions:
      - text: Get space role {id}.
        slots:
          id: path.id
      - text: Show the permissions bundled in space role {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/space-roles/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a space role
      effect: write
      questions:
      - How do I change the permissions in an existing space role?
      - Can I set which role anonymous or guest users are moved to when editing a role?
      instructions:
      - text: Update space role {id} to name {name}, description {description}, permissions {spacePermissions}.
        slots:
          id: path.id
          name: requestBody.name
          description: requestBody.description
          spacePermissions: requestBody.spacePermissions
      - text: Edit role {id} as {name} ({description}) with {spacePermissions}, reassigning guests to {guestReassignmentRoleId}.
        slots:
          id: path.id
          name: requestBody.name
          description: requestBody.description
          spacePermissions: requestBody.spacePermissions
          guestReassignmentRoleId: requestBody.guestReassignmentRoleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/space-roles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a space role
      effect: destructive
      questions:
      - How do I remove a custom space role I no longer need?
      - Who has permission to delete a space role?
      instructions:
      - text: Delete space role {id}.
        slots:
          id: path.id
      - text: Remove the custom role {id} from the site.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/space-role-mode'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the site's space role mode
      effect: read
      questions:
      - Is my Confluence site using role-based access control for spaces?
      - What space role mode is the site in?
      instructions:
      - text: Get the space role mode for this site.
      - text: Tell me whether spaces here run in role-based mode.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/spaces/{id}/role-assignments'].get
  update:
    x-apievangelist-phrasing:
      intent: List who holds which role in a space
      effect: read
      questions:
      - Who has which role in a particular space?
      - Can I see only the people assigned a specific role in a space?
      instructions:
      - text: List the role assignments in space {id}.
        slots:
          id: path.id
      - text: Show who holds role {role-id} in space {id}.
        slots:
          role-id: query.role-id
          id: path.id
      - text: Get the roles assigned to principal {principal-id} in space {id}.
        slots:
          principal-id: query.principal-id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/spaces/{id}/role-assignments'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign or remove roles for people in a space
      effect: write
      questions:
      - How do I give users or groups a role in a space in one call?
      - Can I remove someone's role assignment by leaving out the role?
      instructions:
      - text: Set the role assignments for space {id}.
        slots:
          id: path.id
      - text: Update who holds which role in space {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'