API Evangelist conversational phrasing for OpenAI Roles API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenAI Roles API
  version: 1.0.0
extends: openapi/openai-roles-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: 8
- target: $.paths['/organization/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organization's roles
      effect: read
      questions:
      - Which roles are configured at the organization level?
      - Can I see the custom organization roles we've defined?
      instructions:
      - text: List the organization roles.
      - text: Show {limit} organization-wide roles ordered {order}.
        slots:
          limit: query.limit
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom organization role
      effect: write
      questions:
      - How do I define a custom role for my whole organization?
      - Which permissions can I bundle into a new organization role?
      instructions:
      - text: Create an organization role {role_name} with permissions {permissions}.
        slots:
          role_name: requestBody.role_name
          permissions: requestBody.permissions
      - text: Add org-wide role {role_name} granting {permissions}, described as {description}.
        slots:
          role_name: requestBody.role_name
          permissions: requestBody.permissions
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization/roles/{role_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an organization role
      effect: write
      questions:
      - Can I change the permissions on an existing organization role?
      - Is it possible to rename a custom role at the org level?
      instructions:
      - text: Set organization role {role_id}'s permissions to {permissions}.
        slots:
          role_id: path.role_id
          permissions: requestBody.permissions
      - text: Rename organization role {role_id} to {role_name}.
        slots:
          role_id: path.role_id
          role_name: requestBody.role_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom organization role
      effect: destructive
      questions:
      - How do I remove a custom role from the organization?
      - Can I delete an organization role we no longer use?
      instructions:
      - text: Delete organization role {role_id}.
        slots:
          role_id: path.role_id
      - text: Remove custom org role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the roles in a project
      effect: read
      questions:
      - Which roles are defined inside a particular project?
      - Can I see the custom roles available in one project?
      instructions:
      - text: List the roles in project {project_id}.
        slots:
          project_id: path.project_id
      - text: Show {limit} roles configured for project {project_id}.
        slots:
          limit: query.limit
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom role in a project
      effect: write
      questions:
      - How do I create a role that only applies within one project?
      - Can a project have its own custom set of permissions?
      instructions:
      - text: Create role {role_name} in project {project_id} with permissions {permissions}.
        slots:
          role_name: requestBody.role_name
          project_id: path.project_id
          permissions: requestBody.permissions
      - text: Add a project-scoped role {role_name} to {project_id} granting {permissions}.
        slots:
          role_name: requestBody.role_name
          project_id: path.project_id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/roles/{role_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a role in a project
      effect: write
      questions:
      - Can I change what a project-level role is allowed to do?
      - Is it possible to rename a role inside a project?
      instructions:
      - text: Set role {role_id} in project {project_id} to permissions {permissions}.
        slots:
          role_id: path.role_id
          project_id: path.project_id
          permissions: requestBody.permissions
      - text: Rename project {project_id}'s role {role_id} to {role_name}.
        slots:
          project_id: path.project_id
          role_id: path.role_id
          role_name: requestBody.role_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom role from a project
      effect: destructive
      questions:
      - How do I delete a custom role from a single project?
      - Can I remove a project role that nobody uses anymore?
      instructions:
      - text: Delete role {role_id} from project {project_id}.
        slots:
          role_id: path.role_id
          project_id: path.project_id
      - text: Remove project {project_id}'s custom role {role_id}.
        slots:
          project_id: path.project_id
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'