# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Appwrite Account API
  version: 1.0.0
extends: openapi/appwrite-account-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: 73
- target: $.paths['/account'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the signed-in user's account
      effect: read
      questions:
      - Who is the user currently logged in to my Appwrite app?
      - Can I fetch the profile of the signed-in user from the client side?
      instructions:
      - text: Show me the account details of the currently logged-in user.
      - text: Fetch my own account profile.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new user account
      effect: write
      questions:
      - How do I let a new user sign up with an email and password?
      - What do I need to register someone as a new account in my project?
      instructions:
      - text: Register a new account for {email} with password {password} and user ID {userId}.
        slots:
          email: requestBody.email
          password: requestBody.password
          userId: requestBody.userId
      - text: Sign up {name} as a new user with email {email}, password {password} and ID {userId}.
        slots:
          name: requestBody.name
          email: requestBody.email
          password: requestBody.password
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the signed-in user's account
      effect: destructive
      questions:
      - Can a logged-in user delete their own account?
      - What endpoint removes the current user's whole account?
      instructions:
      - text: Delete my own user account entirely.
      - text: Remove the currently logged-in user's account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/billing-addresses'].get
  update:
    x-apievangelist-phrasing:
      intent: List the account's billing addresses
      effect: read
      questions:
      - Which billing addresses are saved on my account?
      - Can I filter the billing addresses on my account with queries?
      instructions:
      - text: List all billing addresses on my account.
      - text: List my billing addresses matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/billing-addresses'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a billing address to the account
      effect: write
      questions:
      - How do I add a new billing address to my account?
      - Which fields are required when saving a billing address?
      instructions:
      - text: Add a billing address at {streetAddress}, {city}, {country} to my account.
        slots:
          streetAddress: requestBody.streetAddress
          city: requestBody.city
          country: requestBody.country
      - text: Save a new billing address {streetAddress}, {city} {postalCode}, {state}, {country}.
        slots:
          streetAddress: requestBody.streetAddress
          city: requestBody.city
          postalCode: requestBody.postalCode
          state: requestBody.state
          country: requestBody.country
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/billing-addresses/{billingAddressId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one billing address by ID
      effect: read
      questions:
      - Can I look up a single saved billing address by its ID?
      - What details are stored for a specific billing address on my account?
      instructions:
      - text: Show billing address {billingAddressId}.
        slots:
          billingAddressId: path.billingAddressId
      - text: Get the details of my billing address {billingAddressId}.
        slots:
          billingAddressId: path.billingAddressId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/billing-addresses/{billingAddressId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing billing address
      effect: write
      questions:
      - How do I change a billing address I already saved?
      - Can I correct the street or city on an existing billing address?
      instructions:
      - text: Update billing address {billingAddressId} to {streetAddress}, {city}, {country}.
        slots:
          billingAddressId: path.billingAddressId
          streetAddress: requestBody.streetAddress
          city: requestBody.city
          country: requestBody.country
      - text: Change the postal code on billing address {billingAddressId} to {postalCode}, keeping {streetAddress}, {city}, {country}.
        slots:
          billingAddressId: path.billingAddressId
          postalCode: requestBody.postalCode
          streetAddress: requestBody.streetAddress
          city: requestBody.city
          country: requestBody.country
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/billing-addresses/{billingAddressId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a billing address
      effect: destructive
      questions:
      - Can I remove an old billing address from my account?
      - What happens when I delete a saved billing address?
      instructions:
      - text: Delete billing address {billingAddressId}.
        slots:
          billingAddressId: path.billingAddressId
      - text: Remove the billing address {billingAddressId} from my account.
        slots:
          billingAddressId: path.billingAddressId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/consents'].get
  update:
    x-apievangelist-phrasing:
      intent: List OAuth2 consents given to third-party apps
      effect: read
      questions:
      - Which third-party apps have I granted OAuth2 consent to?
      - Can I see every app the current user has authorized?
      instructions:
      - text: List the OAuth2 consents I have given to third-party apps.
      - text: List my app consents matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/consents/{consentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one OAuth2 consent
      effect: read
      questions:
      - What scopes did I grant in a particular OAuth2 consent?
      - Can I look up a single third-party app consent by ID?
      instructions:
      - text: Show OAuth2 consent {consentId}.
        slots:
          consentId: path.consentId
      - text: Get the details of the app consent {consentId}.
        slots:
          consentId: path.consentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/consents/{consentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a third-party app's OAuth2 consent
      effect: destructive
      questions:
      - How do I revoke a third-party app's access to my account?
      - Does withdrawing an OAuth2 consent also revoke the app's tokens?
      instructions:
      - text: Revoke OAuth2 consent {consentId} and all its tokens.
        slots:
          consentId: path.consentId
      - text: Withdraw my consent {consentId} so that app must ask again.
        slots:
          consentId: path.consentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/consents/{consentId}/tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List token families under an OAuth2 consent
      effect: read
      questions:
      - Which devices or sessions hold tokens under an app consent I gave?
      - Are the token secrets returned when I list a consent's tokens?
      instructions:
      - text: List the token families issued under consent {consentId}.
        slots:
          consentId: path.consentId
      - text: Show every authorized device for app consent {consentId}.
        slots:
          consentId: path.consentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/consents/{consentId}/tokens/{tokenId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one token family under a consent
      effect: read
      questions:
      - Can I inspect a single token family issued under an app consent?
      - What metadata is shown for one authorized device of a consent?
      instructions:
      - text: Show token family {tokenId} under consent {consentId}.
        slots:
          tokenId: path.tokenId
          consentId: path.consentId
      - text: Get details of consent {consentId} token {tokenId}.
        slots:
          consentId: path.consentId
          tokenId: path.tokenId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/consents/{consentId}/tokens/{tokenId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke one device's tokens under a consent
      effect: destructive
      questions:
      - Can I sign one device out of a third-party app without revoking the whole consent?
      - Do other devices keep working when I delete one consent token family?
      instructions:
      - text: Revoke token family {tokenId} under consent {consentId}.
        slots:
          tokenId: path.tokenId
          consentId: path.consentId
      - text: Cut off one device, token {tokenId}, from app consent {consentId} but keep the consent.
        slots:
          tokenId: path.tokenId
          consentId: path.consentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/coupons/{couponId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a coupon for my account
      effect: read
      questions:
      - What does a coupon code give my account before I apply it?
      - Can I check a coupon's details from my account?
      instructions:
      - text: Show the details of coupon {couponId} for my account.
        slots:
          couponId: path.couponId
      - text: Check what coupon {couponId} is worth on my account.
        slots:
          couponId: path.couponId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/email'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change the signed-in user's email
      effect: write
      questions:
      - How can a user change the email address on their account?
      - Does changing my email reset its verification status?
      instructions:
      - text: Change my account email to {email}; my password is {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      - text: Update the logged-in user's email address to {email} using password {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/identities'].get
  update:
    x-apievangelist-phrasing:
      intent: List the user's linked login identities
      effect: read
      questions:
      - Which OAuth identities are linked to my account?
      - Can I see the external logins attached to the current user?
      instructions:
      - text: List the identities linked to my account.
      - text: List my linked identities matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/identities/{identityId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a login identity
      effect: destructive
      questions:
      - How do I unlink an OAuth identity from my account?
      - Can I remove one external login provider from my profile?
      instructions:
      - text: Unlink identity {identityId} from my account.
        slots:
          identityId: path.identityId
      - text: Delete the linked identity {identityId}.
        slots:
          identityId: path.identityId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List invoices tied to my account
      effect: read
      questions:
      - Where can I see all invoices billed to my account?
      - Can I filter my account invoices with queries?
      instructions:
      - text: List all invoices on my account.
      - text: List my account invoices matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/jwts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a JWT for the current user
      effect: write
      questions:
      - How do I get a JWT to call the server API on behalf of the logged-in user?
      - How long is an account JWT valid for?
      instructions:
      - text: Create a JSON Web Token for the current user.
      - text: Issue a JWT for me that lasts {duration} seconds.
        slots:
          duration: requestBody.duration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List my account API keys
      effect: read
      questions:
      - Which API keys exist on my personal account?
      - Can I get just the count of my account keys?
      instructions:
      - text: List all API keys on my account.
      - text: Show my account keys with total count set to {total}.
        slots:
          total: query.total
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an account API key
      effect: write
      questions:
      - How do I create a personal account API key with specific scopes?
      - Can an account key be given an expiration date?
      instructions:
      - text: Create an account key named {name} with scopes {scopes}.
        slots:
          name: requestBody.name
          scopes: requestBody.scopes
      - text: Create account key {name} with scopes {scopes} expiring {expire}.
        slots:
          name: requestBody.name
          scopes: requestBody.scopes
          expire: requestBody.expire
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/keys/{keyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one account API key
      effect: read
      questions:
      - What scopes does one of my account keys have?
      - Can I look up a single account API key by ID?
      instructions:
      - text: Show account key {keyId}.
        slots:
          keyId: path.keyId
      - text: Get the scopes of my account key {keyId}.
        slots:
          keyId: path.keyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/keys/{keyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an account API key
      effect: write
      questions:
      - Can I change the scopes on an existing account key?
      - How do I extend the expiry of an account API key?
      instructions:
      - text: Rename account key {keyId} to {name} with scopes {scopes}.
        slots:
          keyId: path.keyId
          name: requestBody.name
          scopes: requestBody.scopes
      - text: Set account key {keyId} to expire at {expire}, keeping name {name} and scopes {scopes}.
        slots:
          keyId: path.keyId
          expire: requestBody.expire
          name: requestBody.name
          scopes: requestBody.scopes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/keys/{keyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an account API key
      effect: destructive
      questions:
      - How do I revoke one of my account API keys?
      - Does a deleted account key stop authenticating immediately?
      instructions:
      - text: Delete account key {keyId}.
        slots:
          keyId: path.keyId
      - text: Revoke my account API key {keyId}.
        slots:
          keyId: path.keyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/logs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the user's security activity logs
      effect: read
      questions:
      - Where can I see recent security activity on my account?
      - Do account logs include IP address and location?
      instructions:
      - text: List my latest account security logs.
      - text: List my activity logs matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa'].patch
  update:
    x-apievangelist-phrasing:
      intent: Turn multi-factor authentication on or off
      effect: write
      questions:
      - How do I enable MFA on my account?
      - Can a user switch off multi-factor authentication?
      instructions:
      - text: Set MFA on my account to {mfa}.
        slots:
          mfa: requestBody.mfa
      - text: Turn on multi-factor authentication for my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/authenticators/{type}'].put
  update:
    x-apievangelist-phrasing:
      intent: Verify a newly added authenticator app
      effect: write
      questions:
      - How do I confirm an authenticator app after adding it?
      - What code do I send to finish setting up a TOTP authenticator?
      instructions:
      - text: Verify my {type} authenticator with code {otp}.
        slots:
          type: path.type
          otp: requestBody.otp
      - text: Confirm the {type} authenticator setup using one-time password {otp}.
        slots:
          type: path.type
          otp: requestBody.otp
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/authenticators/{type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an authenticator app as an MFA factor
      effect: write
      questions:
      - Can I add an authenticator app like TOTP as a second factor?
      - What is the first step to register an authenticator for MFA?
      instructions:
      - text: Add a {type} authenticator to my account.
        slots:
          type: path.type
      - text: Start setting up a new {type} authenticator app for MFA.
        slots:
          type: path.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/authenticators/{type}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an MFA authenticator
      effect: destructive
      questions:
      - How do I remove an authenticator app from my account?
      - Can I delete my TOTP factor if I lost my phone?
      instructions:
      - text: Remove my {type} authenticator.
        slots:
          type: path.type
      - text: Delete the {type} MFA authenticator from my account.
        slots:
          type: path.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/challenges'].put
  update:
    x-apievangelist-phrasing:
      intent: Complete an MFA challenge with a code
      effect: write
      questions:
      - How do I finish MFA verification after sign-in?
      - Where do I submit the one-time password for an MFA challenge?
      instructions:
      - text: Complete MFA challenge {challengeId} with code {otp}.
        slots:
          challengeId: requestBody.challengeId
          otp: requestBody.otp
      - text: Answer challenge {challengeId} using one-time password {otp}.
        slots:
          challengeId: requestBody.challengeId
          otp: requestBody.otp
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/challenges'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an MFA challenge after sign-in
      effect: write
      questions:
      - How do I begin MFA verification once a user has signed in?
      - Which factor types can I request an MFA challenge for?
      instructions:
      - text: Start an MFA challenge using the {factor} factor.
        slots:
          factor: requestBody.factor
      - text: Send me an MFA challenge via {factor}.
        slots:
          factor: requestBody.factor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/factors'].get
  update:
    x-apievangelist-phrasing:
      intent: List available MFA factors
      effect: read
      questions:
      - Which MFA factors are available on my account?
      - Can I check whether email, phone or TOTP factors are enabled for me?
      instructions:
      - text: List the MFA factors available on my account.
      - text: Show which second factors I can use for a challenge.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/recovery-codes'].get
  update:
    x-apievangelist-phrasing:
      intent: Show existing MFA recovery codes
      effect: read
      questions:
      - Can I view the MFA recovery codes I already generated?
      - Is an OTP challenge needed before reading recovery codes?
      instructions:
      - text: Show my existing MFA recovery codes.
      - text: Retrieve the backup recovery codes I generated earlier.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/recovery-codes'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate MFA recovery codes for the first time
      effect: write
      questions:
      - How do I generate backup recovery codes after adding an authenticator?
      - When should recovery codes first be created for MFA?
      instructions:
      - text: Generate my first set of MFA recovery codes.
      - text: Create backup recovery codes for my new authenticator.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/mfa/recovery-codes'].patch
  update:
    x-apievangelist-phrasing:
      intent: Regenerate MFA recovery codes
      effect: write
      questions:
      - Can I replace my MFA recovery codes with a fresh set?
      - What do I do if my existing recovery codes were exposed?
      instructions:
      - text: Regenerate my MFA recovery codes, replacing the old ones.
      - text: Issue a fresh set of recovery codes to replace my current codes.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/name'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change the signed-in user's name
      effect: write
      questions:
      - How can a user change their display name?
      - Can I rename the currently logged-in account?
      instructions:
      - text: Change my account name to {name}.
        slots:
          name: requestBody.name
      - text: Set the logged-in user's name to {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/password'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change the signed-in user's password
      effect: write
      questions:
      - How do I change my password while logged in?
      - Is the old password required for users who signed up with OAuth or magic URL?
      instructions:
      - text: Change my password from {oldPassword} to {password}.
        slots:
          oldPassword: requestBody.oldPassword
          password: requestBody.password
      - text: Set a new password {password} on my account.
        slots:
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved payment methods
      effect: read
      questions:
      - Which payment methods are saved on my account?
      - Can I filter my payment methods with queries?
      instructions:
      - text: List my saved payment methods.
      - text: List payment methods on my account matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods'].post
  update:
    x-apievangelist-phrasing:
      intent: Start adding a new payment method
      effect: write
      questions:
      - How do I add a new card to my account?
      - What is the first step to register a payment method?
      instructions:
      - text: Create a new payment method on my account.
      - text: Start setting up a new card for my account billing.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods/{paymentMethodId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one payment method
      effect: read
      questions:
      - Can I look up a specific saved card by ID?
      - What details are stored for one of my payment methods?
      instructions:
      - text: Show payment method {paymentMethodId}.
        slots:
          paymentMethodId: path.paymentMethodId
      - text: Get details of my card {paymentMethodId}.
        slots:
          paymentMethodId: path.paymentMethodId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods/{paymentMethodId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a payment method
      effect: destructive
      questions:
      - How do I remove an old card from my account?
      - Can I delete a saved payment method?
      instructions:
      - text: Delete payment method {paymentMethodId}.
        slots:
          paymentMethodId: path.paymentMethodId
      - text: Remove card {paymentMethodId} from my account.
        slots:
          paymentMethodId: path.paymentMethodId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods/{paymentMethodId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a card's expiry date
      effect: write
      questions:
      - Can I update the expiry date on a saved card?
      - How do I change the expiration month and year of a payment method?
      instructions:
      - text: Set the expiry of payment method {paymentMethodId} to {expiryMonth}/{expiryYear}.
        slots:
          paymentMethodId: path.paymentMethodId
          expiryMonth: requestBody.expiryMonth
          expiryYear: requestBody.expiryYear
      - text: Update card {paymentMethodId} to expire in month {expiryMonth} of {expiryYear}.
        slots:
          paymentMethodId: path.paymentMethodId
          expiryMonth: requestBody.expiryMonth
          expiryYear: requestBody.expiryYear
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods/{paymentMethodId}/provider'].patch
  update:
    x-apievangelist-phrasing:
      intent: Link a payment method to its provider ID
      effect: write
      questions:
      - How do I attach the payment provider's method ID to my saved card?
      - Can I set the provider method ID and name on a payment method?
      instructions:
      - text: Set payment method {paymentMethodId} provider ID to {providerMethodId} with name {name}.
        slots:
          paymentMethodId: path.paymentMethodId
          providerMethodId: requestBody.providerMethodId
          name: requestBody.name
      - text: Link card {paymentMethodId} to provider method {providerMethodId} named {name}.
        slots:
          paymentMethodId: path.paymentMethodId
          providerMethodId: requestBody.providerMethodId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/payment-methods/{paymentMethodId}/setup'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set up mandates for an Indian card
      effect: write
      questions:
      - How do I set up mandate options for an Indian card payment method?
      - Do Indian cards need a separate mandate setup step?
      instructions:
      - text: Set up mandate options on payment method {paymentMethodId}.
        slots:
          paymentMethodId: path.paymentMethodId
      - text: Configure the Indian card mandate for card {paymentMethodId}.
        slots:
          paymentMethodId: path.paymentMethodId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/phone'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change the signed-in user's phone number
      effect: write
      questions:
      - How can a user change the phone number on their account?
      - Is a confirmation SMS sent automatically after changing my phone?
      instructions:
      - text: Change my phone number to {phone}; password is {password}.
        slots:
          phone: requestBody.phone
          password: requestBody.password
      - text: Update the logged-in user's phone to {phone} using password {password}.
        slots:
          phone: requestBody.phone
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/prefs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the user's saved preferences
      effect: read
      questions:
      - Where are the current user's key-value preferences stored?
      - Can I read my own account preferences object?
      instructions:
      - text: Show my account preferences.
      - text: Fetch the logged-in user's saved prefs.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/prefs'].patch
  update:
    x-apievangelist-phrasing:
      intent: Replace the user's preferences
      effect: write
      questions:
      - How do I save preferences like theme or language for a user?
      - What is the size limit for account preferences?
      instructions:
      - text: Replace my account preferences with {prefs}.
        slots:
          prefs: requestBody.prefs
      - text: Save {prefs} as the logged-in user's preferences.
        slots:
          prefs: requestBody.prefs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/recovery'].put
  update:
    x-apievangelist-phrasing:
      intent: Complete a password reset
      effect: write
      questions:
      - How do I finish a password reset after the user clicks the email link?
      - Which values from the reset link do I need to set a new password?
      instructions:
      - text: Reset the password for user {userId} to {password} using secret {secret}.
        slots:
          userId: requestBody.userId
          password: requestBody.password
          secret: requestBody.secret
      - text: Complete password recovery for {userId} with secret {secret} and new password {password}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/recovery'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a password reset email
      effect: write
      questions:
      - How do I send a forgot-password email to a user?
      - Where does the password reset link redirect the user?
      instructions:
      - text: Send a password reset email to {email} redirecting to {url}.
        slots:
          email: requestBody.email
          url: requestBody.url
      - text: Start password recovery for {email} with reset page {url}.
        slots:
          email: requestBody.email
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the user's active sessions
      effect: read
      questions:
      - On which devices am I currently logged in?
      - Can I see all active sessions for my account?
      instructions:
      - text: List my active sessions across devices.
      - text: Show every device I'm logged in on.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Log out of all devices
      effect: destructive
      questions:
      - How do I sign the user out everywhere at once?
      - Can I delete every session on my account in one call?
      instructions:
      - text: Log me out of all devices.
      - text: Delete every session on my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/anonymous'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an anonymous guest session
      effect: write
      questions:
      - Can users try my app as a guest without signing up?
      - How can an anonymous account later become a normal account?
      instructions:
      - text: Create an anonymous guest session.
      - text: Log this visitor in anonymously.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/email'].post
  update:
    x-apievangelist-phrasing:
      intent: Log in with email and password
      effect: write
      questions:
      - How do I log a user in with their email and password?
      - How many active sessions can one user have at a time?
      instructions:
      - text: Log in as {email} with password {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      - text: Create an email-password session for {email} using {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/magic-url'].put
  update:
    x-apievangelist-phrasing:
      intent: Finish a magic URL login
      effect: write
      questions:
      - What do I call after the user clicks the magic URL link in their email?
      - Which endpoint turns a magic link secret into a session?
      instructions:
      - text: Complete the magic URL login for user {userId} with secret {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      - text: Turn magic link secret {secret} for {userId} into a session.
        slots:
          secret: requestBody.secret
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/oauth2/{provider}'].get
  update:
    x-apievangelist-phrasing:
      intent: Log in with an OAuth2 provider
      effect: read
      questions:
      - Can users log in to my app through a third-party OAuth2 provider they already have an account with?
      - Where does the user land after an OAuth2 login succeeds or fails?
      instructions:
      - text: Start an OAuth2 login with {provider}.
        slots:
          provider: path.provider
      - text: Sign in via {provider} and redirect to {success} on success or {failure} on failure.
        slots:
          provider: path.provider
          success: query.success
          failure: query.failure
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account/sessions/phone'].put
  update:
    x-apievangelist-phrasing:
      intent: Finish a phone SMS login
      effect: write
      questions:
      - What do I call after the user enters the SMS code to log in?
      - Can I create a session from a phone login secret?
      instructions:
      - text: Complete the phone login for user {userId} with SMS secret {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      - text: Turn phone code {secret} for {userId} into a session.
        slots:
          secret: requestBody.secret
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a session from any login token
      effect: write
      questions:
      - Is there one generic endpoint to exchange a login token for a session?
      - How do I exchange an email OTP token for a session?
      instructions:
      - text: Exchange token secret {secret} for user {userId} into a session.
        slots:
          secret: requestBody.secret
          userId: requestBody.userId
      - text: Create a session using the generic token endpoint for {userId} and {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/{sessionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one session, or the current one
      effect: read
      questions:
      - How do I get details about the session I'm using right now?
      - Can I look up a specific login session by ID?
      instructions:
      - text: Show session {sessionId}.
        slots:
          sessionId: path.sessionId
      - text: Get my current session details.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/{sessionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Log out of one session or device
      effect: destructive
      questions:
      - How do I log the user out on this device only?
      - Can I sign out a single other device remotely?
      instructions:
      - text: Log out session {sessionId}.
        slots:
          sessionId: path.sessionId
      - text: Log me out on this device.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/sessions/{sessionId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Extend a session or refresh its OAuth token
      effect: write
      questions:
      - Can I extend a session that is about to expire?
      - Does refreshing a session also renew the OAuth provider's access token?
      instructions:
      - text: Extend session {sessionId}.
        slots:
          sessionId: path.sessionId
      - text: Refresh the OAuth access token on session {sessionId}.
        slots:
          sessionId: path.sessionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/status'].patch
  update:
    x-apievangelist-phrasing:
      intent: Block the signed-in user's account
      effect: destructive
      questions:
      - Can a user deactivate their own account without deleting it?
      - What happens to the user record when an account is blocked?
      instructions:
      - text: Block my account permanently.
      - text: Deactivate the logged-in user's account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/targets/push'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a device for push notifications
      effect: write
      questions:
      - How do I register a device token for push notifications?
      - Can I choose which provider sends pushes to a device?
      instructions:
      - text: Register device token {identifier} as push target {targetId}.
        slots:
          identifier: requestBody.identifier
          targetId: requestBody.targetId
      - text: Add push target {targetId} for device {identifier} using provider {providerId}.
        slots:
          targetId: requestBody.targetId
          identifier: requestBody.identifier
          providerId: requestBody.providerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/targets/{targetId}/push'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a push target's device token
      effect: write
      questions:
      - What do I do when a device's push token changes?
      - Can I update the identifier on an existing push target?
      instructions:
      - text: Update push target {targetId} with new device token {identifier}.
        slots:
          targetId: path.targetId
          identifier: requestBody.identifier
      - text: Replace the device token on push target {targetId} with {identifier}.
        slots:
          targetId: path.targetId
          identifier: requestBody.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/targets/{targetId}/push'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop push notifications to a device
      effect: destructive
      questions:
      - How do I stop sending push notifications to a device?
      - Can a user remove their own push target?
      instructions:
      - text: Delete push target {targetId}.
        slots:
          targetId: path.targetId
      - text: Unregister device push target {targetId}.
        slots:
          targetId: path.targetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/tokens/email'].post
  update:
    x-apievangelist-phrasing:
      intent: Email a one-time login code
      effect: write
      questions:
      - Can users log in with a one-time code sent by email?
      - Does sending an email OTP create a new account for an unknown address?
      instructions:
      - text: Email a one-time login code to {email} for user {userId}.
        slots:
          email: requestBody.email
          userId: requestBody.userId
      - text: Send an email OTP to {email} as user {userId} with a security phrase set to {phrase}.
        slots:
          email: requestBody.email
          userId: requestBody.userId
          phrase: requestBody.phrase
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/tokens/magic-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Email a magic login link
      effect: write
      questions:
      - How do I send a passwordless magic link to a user's email?
      - Where does the magic URL redirect the user after they click it?
      instructions:
      - text: Send a magic login link to {email} for user {userId}.
        slots:
          email: requestBody.email
          userId: requestBody.userId
      - text: Email a magic URL to {email} as {userId} that returns to {url}.
        slots:
          email: requestBody.email
          userId: requestBody.userId
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/tokens/oauth2/{provider}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an OAuth2 login token instead of a session
      effect: read
      questions:
      - Can I get a token from an OAuth2 login rather than a session cookie?
      - Which OAuth2 flow suits server-side rendered apps that create their own session?
      instructions:
      - text: Start an OAuth2 token flow with {provider}.
        slots:
          provider: path.provider
      - text: Get an OAuth2 login token via {provider}, returning to {success}.
        slots:
          provider: path.provider
          success: query.success
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/tokens/phone'].post
  update:
    x-apievangelist-phrasing:
      intent: Text a login code to a phone
      effect: write
      questions:
      - How do users log in with a code sent by SMS?
      - Does an SMS login create a new user if the ID is unknown?
      instructions:
      - text: Text a login code to {phone} for user {userId}.
        slots:
          phone: requestBody.phone
          userId: requestBody.userId
      - text: Send an SMS login token to {phone} as {userId}.
        slots:
          phone: requestBody.phone
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/verifications/email'].put
  update:
    x-apievangelist-phrasing:
      intent: Confirm a user's email address
      effect: write
      questions:
      - How do I finish email verification after the user clicks the link?
      - Which values from the verification link confirm email ownership?
      instructions:
      - text: Confirm the email of user {userId} with secret {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      - text: Complete email verification for {userId} using {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/verifications/email'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an email verification link
      effect: write
      questions:
      - How do I send a verification email to the logged-in user?
      - Can I set the page the email verification link points to?
      instructions:
      - text: Send me an email verification link pointing to {url}.
        slots:
          url: requestBody.url
      - text: Email a confirm-your-address link that returns to {url}.
        slots:
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/verifications/phone'].put
  update:
    x-apievangelist-phrasing:
      intent: Confirm a user's phone number
      effect: write
      questions:
      - How do I finish phone verification with the SMS code?
      - What do I submit to mark a phone number as verified?
      instructions:
      - text: Confirm the phone of user {userId} with SMS secret {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      - text: Complete phone verification for {userId} using code {secret}.
        slots:
          userId: requestBody.userId
          secret: requestBody.secret
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/verifications/phone'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a phone verification SMS
      effect: write
      questions:
      - How do I text a verification code to the user's new phone number?
      - Can I resend the phone verification SMS after updating a number?
      instructions:
      - text: Send a verification SMS to my phone.
      - text: Text the logged-in user a phone verification code.
      method: generated
      generated: '2026-09-26'