# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Nylas Manage Grants API
  version: 1.0.0
extends: openapi/nylas-manage-grants-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: 6
- target: $.paths['/v3/connect/custom'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a grant from my own OAuth refresh token
      effect: write
      questions:
      - If I run the OAuth flow myself, how do I connect a user's account with their refresh token?
      - Can I migrate existing users by handing over tokens instead of re-authenticating them?
      instructions:
      - text: Create a grant using Bring Your Own Authentication.
      - text: Connect this user's account with the refresh token from my own OAuth flow.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants'].get
  update:
    x-apievangelist-phrasing:
      intent: List connected user accounts (grants)
      effect: read
      questions:
      - How do I list every user account connected to my application?
      - Can I find grants that are invalid and need re-authentication?
      - Is there a way to look up grants by email address or provider?
      instructions:
      - text: List grants with status {grant_status}.
        slots:
          grant_status: query.grant_status
      - text: Find the grant for {email}.
        slots:
          email: query.email
      - text: Show all grants from provider {provider}.
        slots:
          provider: query.provider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grantId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one connected account
      effect: read
      questions:
      - How can I tell whether a specific user's grant has expired?
      - Can I see the email aliases on a particular grant?
      instructions:
      - text: Get grant {grantId}.
        slots:
          grantId: path.grantId
      - text: Check the status of connected account {grantId}.
        slots:
          grantId: path.grantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grantId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Disconnect a user's account (delete grant)
      effect: destructive
      questions:
      - What happens if I delete a grant and the user later signs in again?
      - How do I disconnect a user's email account from my app?
      instructions:
      - text: Delete grant {grantId}.
        slots:
          grantId: path.grantId
      - text: Disconnect user account {grantId} from my application.
        slots:
          grantId: path.grantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grantId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rotate a grant's refresh token or scopes
      effect: write
      questions:
      - Can I store a new refresh token on a grant without recreating it?
      - Does updating a grant's scope list change what the provider actually allows?
      instructions:
      - text: Replace the settings on grant {grantId} with {settings}.
        slots:
          grantId: path.grantId
          settings: requestBody.settings
      - text: Update the stored scopes on grant {grantId} to {scope}.
        slots:
          grantId: path.grantId
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/me'].get
  update:
    x-apievangelist-phrasing:
      intent: Identify the grant behind my access token
      effect: read
      questions:
      - Which grant does the access token I'm using belong to?
      - Can I look up the current user's grant without knowing its ID?
      instructions:
      - text: Show the grant for my current access token.
      - text: Tell me which connected account this token represents.
      method: generated
      generated: '2026-09-26'