# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Flagsmith Permissions API
  version: 1.0.0
extends: openapi/flagsmith-permissions-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: 34
- target: $.paths['/api/v1/environments/{environment_api_key}/user-group-permissions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List group permissions on an environment
      effect: read
      questions:
      - Which user groups have access to this environment?
      - What permissions does each group hold on a single environment?
      instructions:
      - text: List the group permission grants on environment {environment_api_key}.
        slots:
          environment_api_key: path.environment_api_key
      - text: Show which teams can act in environment {environment_api_key} and with what rights.
        slots:
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-group-permissions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a group access to an environment
      effect: write
      questions:
      - How do I give a whole team permissions on one environment?
      - Can I make a group an admin of a specific environment?
      instructions:
      - text: Grant group {group} permissions {permissions} on environment {environment_api_key}.
        slots:
          group: requestBody.group
          permissions: requestBody.permissions
          environment_api_key: path.environment_api_key
      - text: Make group {group} an environment admin ({admin}) in {environment_api_key}.
        slots:
          group: requestBody.group
          admin: requestBody.admin
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-group-permissions/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one group's environment permission grant
      effect: read
      questions:
      - What exactly can a given group do in this environment?
      - Is a particular group grant on an environment an admin grant?
      instructions:
      - text: Show environment group grant {id} in {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      - text: Tell me whether group permission record {id} on environment {environment_api_key} includes admin.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-group-permissions/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a group's environment permissions
      effect: write
      questions:
      - Can I overwrite the full set of rights a team has on an environment?
      - What must I resend to replace a group's environment grant?
      instructions:
      - text: Replace environment group grant {id} in {environment_api_key} so group {group} has exactly {permissions}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          group: requestBody.group
          permissions: requestBody.permissions
      - text: Overwrite the environment {environment_api_key} grant {id} for group {group}, admin set to {admin}.
        slots:
          environment_api_key: path.environment_api_key
          id: path.id
          group: requestBody.group
          admin: requestBody.admin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-group-permissions/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a group's environment access
      effect: destructive
      questions:
      - How do I take a team's access away from an environment?
      - Can I remove one group's environment grant without touching its project rights?
      instructions:
      - text: Revoke environment group grant {id} in {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      - text: Remove the team permission record {id} from environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-group-permissions/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a group's environment grant
      effect: write
      questions:
      - Can I just toggle admin on a group's environment grant?
      - Is it possible to tweak a team's environment rights without resending the group?
      instructions:
      - text: Patch environment group grant {id} in {environment_api_key} to set admin {admin}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          admin: requestBody.admin
      - text: Change only the permission list of team grant {id} on environment {environment_api_key} to {permissions}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-permissions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List user permissions on an environment
      effect: read
      questions:
      - Which individual users have direct access to this environment?
      - What rights does each person hold on one environment?
      instructions:
      - text: List the individual user grants on environment {environment_api_key}.
        slots:
          environment_api_key: path.environment_api_key
      - text: Show which people have direct permissions in environment {environment_api_key}.
        slots:
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-permissions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user access to an environment
      effect: write
      questions:
      - How do I give one person permissions on a single environment?
      - Can I make an individual user an environment admin?
      instructions:
      - text: Grant user {user} permissions {permissions} on environment {environment_api_key}.
        slots:
          user: requestBody.user
          permissions: requestBody.permissions
          environment_api_key: path.environment_api_key
      - text: Make person {user} an admin ({admin}) of environment {environment_api_key}.
        slots:
          user: requestBody.user
          admin: requestBody.admin
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-permissions/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's environment permission grant
      effect: read
      questions:
      - What can a specific person do in this environment?
      - Does a given user grant on an environment include admin?
      instructions:
      - text: Show environment user grant {id} in {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      - text: Tell me the rights in individual permission record {id} for environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-permissions/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a user's environment permissions
      effect: write
      questions:
      - Can I overwrite everything a person is allowed to do in an environment?
      - What does a full replacement of a user's environment grant need?
      instructions:
      - text: Replace environment user grant {id} in {environment_api_key} so user {user} has exactly {permissions}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          user: requestBody.user
          permissions: requestBody.permissions
      - text: Overwrite person {user}'s grant {id} on environment {environment_api_key} with admin {admin}.
        slots:
          user: requestBody.user
          id: path.id
          environment_api_key: path.environment_api_key
          admin: requestBody.admin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-permissions/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's environment access
      effect: destructive
      questions:
      - How do I remove one person's direct access to an environment?
      - Will revoking a user's environment grant also drop their group-based access?
      instructions:
      - text: Revoke environment user grant {id} in {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      - text: Delete the individual permission record {id} on environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/user-permissions/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a user's environment grant
      effect: write
      questions:
      - Can I just flip admin on for a person in an environment?
      - Is a partial change to one user's environment rights possible?
      instructions:
      - text: Patch environment user grant {id} in {environment_api_key} to admin {admin}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          admin: requestBody.admin
      - text: Change only the permission keys on person grant {id} in environment {environment_api_key} to {permissions}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-group-permissions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List group permissions on an organisation
      effect: read
      questions:
      - Which groups hold organisation-level permissions?
      - Can I see the organisation grant for just one group?
      instructions:
      - text: List the group permission grants in organisation {organisation_pk}.
        slots:
          organisation_pk: path.organisation_pk
      - text: Show organisation {organisation_pk} permissions for group {group}.
        slots:
          organisation_pk: path.organisation_pk
          group: query.group
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-group-permissions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a group organisation-level permissions
      effect: write
      questions:
      - How do I let a team create projects across the organisation?
      - Can I give a group organisation-wide rights?
      instructions:
      - text: Grant group {group} organisation permissions {permissions} in {organisation_pk}.
        slots:
          group: requestBody.group
          permissions: requestBody.permissions
          organisation_pk: path.organisation_pk
      - text: Give team {group} organisation-wide access in organisation {organisation_pk}.
        slots:
          group: requestBody.group
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-group-permissions/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a group's organisation permissions
      effect: write
      questions:
      - Can I overwrite a team's organisation-level rights in one go?
      - What does replacing a group's organisation grant require?
      instructions:
      - text: Replace organisation group grant {id} in {organisation_pk} so group {group} has exactly {permissions}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          group: requestBody.group
          permissions: requestBody.permissions
      - text: Overwrite team {group}'s organisation-wide grant {id} in {organisation_pk}.
        slots:
          group: requestBody.group
          id: path.id
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-group-permissions/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a group's organisation permissions
      effect: destructive
      questions:
      - How do I strip a team's organisation-level rights?
      - Can I remove a group's organisation grant but keep the group itself?
      instructions:
      - text: Revoke organisation group grant {id} in {organisation_pk}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
      - text: Delete team permission record {id} at organisation level in {organisation_pk}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-group-permissions/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a group's organisation grant
      effect: write
      questions:
      - Can I change just the permission list on a team's organisation grant?
      - Is it possible to patch a group's organisation rights without resending the group?
      instructions:
      - text: Patch organisation group grant {id} in {organisation_pk} to permissions {permissions}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          permissions: requestBody.permissions
      - text: Point organisation grant {id} in {organisation_pk} at a different group, {group}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          group: requestBody.group
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-permissions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List user permissions on an organisation
      effect: read
      questions:
      - Which people hold organisation-level permissions directly?
      - What organisation rights does one particular user have?
      instructions:
      - text: List the individual user grants in organisation {organisation_pk}.
        slots:
          organisation_pk: path.organisation_pk
      - text: Show organisation {organisation_pk} permissions held by user {user}.
        slots:
          organisation_pk: path.organisation_pk
          user: query.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-permissions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user organisation-level permissions
      effect: write
      questions:
      - How do I give one person organisation-wide rights?
      - Can an individual user be allowed to create projects in the organisation?
      instructions:
      - text: Grant user {user} organisation permissions {permissions} in {organisation_pk}.
        slots:
          user: requestBody.user
          permissions: requestBody.permissions
          organisation_pk: path.organisation_pk
      - text: Give person {user} direct organisation-level access in {organisation_pk}.
        slots:
          user: requestBody.user
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-permissions/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a user's organisation permissions
      effect: write
      questions:
      - Can I overwrite everything a person may do across the organisation?
      - What must a full replacement of a user's organisation grant include?
      instructions:
      - text: Replace organisation user grant {id} in {organisation_pk} so user {user} has exactly {permissions}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          user: requestBody.user
          permissions: requestBody.permissions
      - text: Overwrite person {user}'s organisation-wide grant {id} in {organisation_pk}.
        slots:
          user: requestBody.user
          id: path.id
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-permissions/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's organisation permissions
      effect: destructive
      questions:
      - How do I remove a person's direct organisation-level rights?
      - Does revoking a user's organisation grant remove them from the organisation?
      instructions:
      - text: Revoke organisation user grant {id} in {organisation_pk}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
      - text: Delete individual permission record {id} at organisation level in {organisation_pk}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/user-permissions/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a user's organisation grant
      effect: write
      questions:
      - Can I change only the permission keys on a person's organisation grant?
      - Is patching one user's organisation rights possible without resending the user?
      instructions:
      - text: Patch organisation user grant {id} in {organisation_pk} to permissions {permissions}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          permissions: requestBody.permissions
      - text: Reassign organisation grant {id} in {organisation_pk} to person {user}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-group-permissions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List group permissions on a project
      effect: read
      questions:
      - Which teams have access to this project?
      - What rights does each group hold on one project?
      instructions:
      - text: List the group permission grants on project {project_pk}.
        slots:
          project_pk: path.project_pk
      - text: Show which teams can work in project {project_pk} and with what rights.
        slots:
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-group-permissions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a group access to a project
      effect: write
      questions:
      - How do I give a team permissions across a whole project?
      - Can I make a group a project admin?
      instructions:
      - text: Grant group {group} permissions {permissions} on project {project_pk}.
        slots:
          group: requestBody.group
          permissions: requestBody.permissions
          project_pk: path.project_pk
      - text: Make team {group} a project admin ({admin}) in project {project_pk}.
        slots:
          group: requestBody.group
          admin: requestBody.admin
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-group-permissions/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one group's project permission grant
      effect: read
      questions:
      - What exactly can a given team do in this project?
      - Is a specific group grant on a project an admin grant?
      instructions:
      - text: Show project group grant {id} in project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      - text: Tell me whether team permission record {id} on project {project_pk} includes admin.
        slots:
          id: path.id
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-group-permissions/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a group's project permissions
      effect: write
      questions:
      - Can I overwrite the full set of rights a team has on a project?
      - What must I resend to replace a group's project grant?
      instructions:
      - text: Replace project group grant {id} in {project_pk} so group {group} has exactly {permissions}.
        slots:
          id: path.id
          project_pk: path.project_pk
          group: requestBody.group
          permissions: requestBody.permissions
      - text: Overwrite team {group}'s grant {id} on project {project_pk} with admin {admin}.
        slots:
          group: requestBody.group
          id: path.id
          project_pk: path.project_pk
          admin: requestBody.admin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-group-permissions/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a group's project access
      effect: destructive
      questions:
      - How do I take a team's access away from a project?
      - Can I drop one group's project grant while leaving its environment rights?
      instructions:
      - text: Revoke project group grant {id} in project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      - text: Remove team permission record {id} from project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-group-permissions/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a group's project grant
      effect: write
      questions:
      - Can I just toggle admin on a team's project grant?
      - Is it possible to tweak a group's project rights without resending the group?
      instructions:
      - text: Patch project group grant {id} in {project_pk} to set admin {admin}.
        slots:
          id: path.id
          project_pk: path.project_pk
          admin: requestBody.admin
      - text: Change only the permission list of team grant {id} on project {project_pk} to {permissions}.
        slots:
          id: path.id
          project_pk: path.project_pk
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-permissions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List user permissions on a project
      effect: read
      questions:
      - Which individual people have direct access to this project?
      - What rights does each user hold on one project?
      instructions:
      - text: List the individual user grants on project {project_pk}.
        slots:
          project_pk: path.project_pk
      - text: Show which people have direct permissions in project {project_pk}.
        slots:
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-permissions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user access to a project
      effect: write
      questions:
      - How do I give one person permissions on a project?
      - Can I make an individual user a project admin?
      instructions:
      - text: Grant user {user} permissions {permissions} on project {project_pk}.
        slots:
          user: requestBody.user
          permissions: requestBody.permissions
          project_pk: path.project_pk
      - text: Make person {user} an admin ({admin}) of project {project_pk}.
        slots:
          user: requestBody.user
          admin: requestBody.admin
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-permissions/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's project permission grant
      effect: read
      questions:
      - What can a specific person do in this project?
      - Does a given user grant on a project include admin?
      instructions:
      - text: Show project user grant {id} in project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      - text: Tell me the rights in individual permission record {id} for project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-permissions/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a user's project permissions
      effect: write
      questions:
      - Can I overwrite everything a person is allowed to do in a project?
      - What does a full replacement of a user's project grant need?
      instructions:
      - text: Replace project user grant {id} in {project_pk} so user {user} has exactly {permissions}.
        slots:
          id: path.id
          project_pk: path.project_pk
          user: requestBody.user
          permissions: requestBody.permissions
      - text: Overwrite person {user}'s grant {id} on project {project_pk} with admin {admin}.
        slots:
          user: requestBody.user
          id: path.id
          project_pk: path.project_pk
          admin: requestBody.admin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-permissions/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's project access
      effect: destructive
      questions:
      - How do I remove one person's direct access to a project?
      - Will revoking a user's project grant also drop their team-based project access?
      instructions:
      - text: Revoke project user grant {id} in project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      - text: Delete the individual permission record {id} on project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/user-permissions/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a user's project grant
      effect: write
      questions:
      - Can I just flip admin on for a person in a project?
      - Is a partial change to one user's project rights possible?
      instructions:
      - text: Patch project user grant {id} in {project_pk} to admin {admin}.
        slots:
          id: path.id
          project_pk: path.project_pk
          admin: requestBody.admin
      - text: Change only the permission keys on person grant {id} in project {project_pk} to {permissions}.
        slots:
          id: path.id
          project_pk: path.project_pk
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'