# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Akuity Platform API — Custom Roles Custom Role Service API
  version: 1.0.0
extends: openapi/akuity-customroleservice-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/api/v1/customroles'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom roles in an organization
      effect: read
      questions:
      - Which custom roles have we defined in our Akuity organization?
      - Can I see all custom RBAC roles for one organization?
      instructions:
      - text: List the custom roles.
      - text: Show every custom role in organization {organization}.
        slots:
          organization: query.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/customroles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom role
      effect: write
      questions:
      - How do I define a new role with my own permission policy?
      - Can I give a custom role a description when creating it?
      instructions:
      - text: Create a custom role named {name} with policy {policy}.
        slots:
          name: requestBody.name
          policy: requestBody.policy
      - text: Add role {name} to organization {organization} described as {description}.
        slots:
          name: requestBody.name
          organization: requestBody.organizationId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/customroles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom role's definition
      effect: read
      questions:
      - What permissions does a particular custom role grant?
      - Can I look up a single custom role by ID?
      instructions:
      - text: Show custom role {id}.
        slots:
          id: path.id
      - text: Read the policy attached to role {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/customroles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom role
      effect: destructive
      questions:
      - How do I remove a custom role we no longer use?
      - Is deleting a custom role permanent?
      instructions:
      - text: Delete custom role {id}.
        slots:
          id: path.id
      - text: Remove role {id} from the organization permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/customroles/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing custom role
      effect: write
      questions:
      - How do I change the permission policy on an existing custom role?
      - Can I rename a custom role after it's created?
      instructions:
      - text: Update custom role {id} to use policy {policy}.
        slots:
          id: path.id
          policy: requestBody.policy
      - text: Rename existing role {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'