# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snowflake Role API
  version: 1.0.0
extends: openapi/snowflake-role-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: 14
- target: $.paths['/api/v2/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List account roles
      effect: read
      questions:
      - Which roles exist in my Snowflake account?
      - Can I see all account-level roles and who owns them?
      instructions:
      - text: List all roles in the account.
      - text: Show me every account role.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a new account role for a team?
      - Can I add a comment describing a role when I create it?
      instructions:
      - text: Create a role named {name}.
        slots:
          name: requestBody.name
      - text: Create role {name} with the description {comment}.
        slots:
          name: requestBody.name
          comment: requestBody.comment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Drop a role
      effect: destructive
      questions:
      - How do I drop a role nobody uses anymore?
      - Can I delete an account role through the API?
      instructions:
      - text: Drop role {name}.
        slots:
          name: path.name
      - text: Delete the role I named from the account.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/grants'].get
  update:
    x-apievangelist-phrasing:
      intent: List privileges granted to a role
      effect: read
      questions:
      - What privileges does this role currently hold?
      - Which objects can this role access today?
      instructions:
      - text: List the grants given to role {name}.
        slots:
          name: path.name
      - text: Show every privilege this role has been granted.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/grants'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant privileges on an object to a role
      effect: write
      questions:
      - How do I give a role SELECT on a table?
      - Can I grant privileges with the grant option so the role can pass them on?
      instructions:
      - text: Grant {privileges} on {securable_type} {securable} to role {name}.
        slots:
          privileges: requestBody.privileges
          securable_type: requestBody.securable_type
          securable: requestBody.securable
          name: path.name
      - text: Grant {privileges} on {securable_type} {securable} to this role with grant option {grant_option}.
        slots:
          privileges: requestBody.privileges
          securable_type: requestBody.securable_type
          securable: requestBody.securable
          grant_option: requestBody.grant_option
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/grants:revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke privileges from a role
      effect: destructive
      questions:
      - Can I take a privilege away from a role?
      - How do I remove a role's access to one existing object?
      instructions:
      - text: Revoke {privileges} on {securable_type} {securable} from role {name}.
        slots:
          privileges: requestBody.privileges
          securable_type: requestBody.securable_type
          securable: requestBody.securable
          name: path.name
      - text: Remove this role's existing grant on {securable_type} {securable}.
        slots:
          securable_type: requestBody.securable_type
          securable: requestBody.securable
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/grants-of'].get
  update:
    x-apievangelist-phrasing:
      intent: List who has been granted a role
      effect: read
      questions:
      - Which users and roles have been granted this role?
      - Who inherits this role?
      instructions:
      - text: List the users and roles that role {name} is granted to.
        slots:
          name: path.name
      - text: Show who holds this role.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/grants-on'].get
  update:
    x-apievangelist-phrasing:
      intent: List grants on a role object
      effect: read
      questions:
      - What privileges have been granted on the role itself, such as ownership?
      - Which role owns or can modify this role?
      instructions:
      - text: List the grants on role {name} as an object.
        slots:
          name: path.name
      - text: Show who has ownership or other privileges on this role.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/future-grants'].get
  update:
    x-apievangelist-phrasing:
      intent: List future grants to a role
      effect: read
      questions:
      - Which future grants will apply to this role for objects not yet created?
      - Does this role automatically get access to new tables in a schema?
      instructions:
      - text: List the future grants assigned to role {name}.
        slots:
          name: path.name
      - text: Show the privileges this role will receive on objects created later.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/future-grants'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant privileges on future objects to a role
      effect: write
      questions:
      - How can a role automatically get SELECT on every table created in a schema from now on?
      - Can I set up grants for objects that don't exist yet?
      instructions:
      - text: Grant {privileges} on all future {securable_type} objects in {containing_scope} to role {name}.
        slots:
          privileges: requestBody.privileges
          securable_type: requestBody.securable_type
          containing_scope: requestBody.containing_scope
          name: path.name
      - text: Set up a future grant of {privileges} on new {securable_type} objects for this role.
        slots:
          privileges: requestBody.privileges
          securable_type: requestBody.securable_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}/future-grants:revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke future grants from a role
      effect: destructive
      questions:
      - Can I stop a role from automatically getting access to newly created objects?
      - How do I remove a future grant I set up earlier?
      instructions:
      - text: Revoke role {name}'s future grant of {privileges} on {securable_type} objects in {containing_scope}.
        slots:
          name: path.name
          privileges: requestBody.privileges
          securable_type: requestBody.securable_type
          containing_scope: requestBody.containing_scope
      - text: Remove this role's future grants on new {securable_type} objects.
        slots:
          securable_type: requestBody.securable_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}:set-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Set tags on a role
      effect: write
      questions:
      - How do I tag a role for governance tracking?
      - Can I label a role with a department tag?
      instructions:
      - text: Set tags on role {name}.
        slots:
          name: path.name
      - text: Apply my tag assignments to the role I named.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}:unset-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove tags from a role
      effect: write
      questions:
      - Can I remove tags from a role?
      - What's the way to clear a tag off an account role?
      instructions:
      - text: Unset the tags on role {name}.
        slots:
          name: path.name
      - text: Remove the tag assignments from the role I named.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/roles/{name}:get-tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tags assigned to a role
      effect: read
      questions:
      - Which tags are assigned to this role?
      - Does reading a role's tags require an active warehouse?
      instructions:
      - text: Show every tag assigned to role {name}.
        slots:
          name: path.name
      - text: List the tag assignments on the role I named.
      method: generated
      generated: '2026-10-01'