# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Tray Ai Users API
  version: 1.0.0
extends: openapi/tray-ai-users-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: 19
- target: $.paths['/graphql'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an external user for embedded
      effect: write
      questions:
      - How do I add one of my customers as an external user with the GraphQL createExternalUser mutation?
      - Can I mark a new external user as a test user so they are excluded from billing?
      instructions:
      - text: Run the createExternalUser GraphQL mutation with name and externalUserId in {variables}.
        slots:
          variables: requestBody.variables
      - text: Send GraphQL mutation {mutation} to create an external test user.
        slots:
          mutation: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/graphql#getUsers'].post
  update:
    x-apievangelist-phrasing:
      intent: Query external users via GraphQL
      effect: read
      questions:
      - Which external users exist in my embedded application, queried over GraphQL?
      - Does the GraphQL getUsers query return a pagination cursor?
      instructions:
      - text: Run the getUsers GraphQL query {query} with my master token.
        slots:
          query: requestBody.query
      - text: Query GraphQL for external users after cursor {variables}.
        slots:
          variables: requestBody.variables
      method: generated
      generated: '2026-09-26'
- target: $.paths['/graphql#updateExternalUser'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an external user's properties
      effect: write
      questions:
      - Can I flag an existing external user as a test user after creating them?
      - Which GraphQL mutation changes an external user's properties?
      instructions:
      - text: Run the updateExternalUser GraphQL mutation with {variables}.
        slots:
          variables: requestBody.variables
      - text: Send GraphQL mutation {mutation} to mark an external user as a test user.
        slots:
          mutation: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/graphql#removeUser'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove an external user and their data
      effect: destructive
      questions:
      - Does removing an external user with the GraphQL removeUser mutation also delete their solution instances and authentications?
      - How do I offboard a customer from my embedded application completely?
      instructions:
      - text: Run the removeUser GraphQL mutation for external user {user}.
        slots:
          user: requestBody.variables
      - text: Send GraphQL mutation {mutation} to remove an external user with all their instances and auths.
        slots:
          mutation: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/'].post
  update:
    x-apievangelist-phrasing:
      intent: Get users via the embedded root endpoint
      effect: read
      questions:
      - Can I list embedded users by posting to the embedded root endpoint with a master token?
      - Which embedded root call returns my end users?
      instructions:
      - text: Post a get-users request to the embedded root with {variables}.
        slots:
          variables: requestBody.variables
      - text: Fetch end users through the embedded root endpoint using my master token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ '].post
  update:
    x-apievangelist-phrasing:
      intent: Create an end user via the embedded root
      effect: write
      questions:
      - Is there an embedded root call that creates a new end user with a master token?
      - Which master-token request posted to the embedded root adds an end user?
      instructions:
      - text: Post a create-new-user request to the embedded root with {variables}.
        slots:
          variables: requestBody.variables
      - text: Add a new end user through the embedded root endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/  '].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user token via the embedded root
      effect: write
      questions:
      - Can I mint a user token by posting to the embedded root with a master token?
      - Which embedded root call gives me a bearer token scoped to one end user?
      instructions:
      - text: Post a create-user-token request to the embedded root for user {variables}.
        slots:
          variables: requestBody.variables
      - text: Mint a user-scoped token through the embedded root endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/   '].post
  update:
    x-apievangelist-phrasing:
      intent: Create an auth code for the config wizard
      effect: write
      questions:
      - How do I get an authorization code to open the Auth or Config dialog for an end user?
      - What do I need before showing the configuration wizard to a user?
      instructions:
      - text: Create a config wizard authorization code for user {variables}.
        slots:
          variables: requestBody.variables
      - text: Generate an Auth/Config dialog code using my master token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/    '].post
  update:
    x-apievangelist-phrasing:
      intent: Update an end user via the embedded root
      effect: write
      questions:
      - Can I update an end user by posting to the embedded root with a master token?
      - Which embedded root call edits an existing end user?
      instructions:
      - text: Post an update-user request to the embedded root with {variables}.
        slots:
          variables: requestBody.variables
      - text: Edit an end user through the embedded root endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/     '].post
  update:
    x-apievangelist-phrasing:
      intent: Delete an end user via the embedded root
      effect: destructive
      questions:
      - Is there an embedded root call that deletes an end user with a master token?
      - Which master-token request posted to the embedded root deletes a user?
      instructions:
      - text: Post a delete-user request to the embedded root for {variables}.
        slots:
          variables: requestBody.variables
      - text: Delete an end user through the embedded root endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List organization users with roles (unversioned)
      effect: read
      questions:
      - Who are the members of my Tray organization and what roles do they have?
      - Can I see members' emails and roles on the unversioned /users endpoint?
      instructions:
      - text: List users in my organization from the unversioned users endpoint.
      - text: Show each organization member's name, email and role.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a user by email (unversioned)
      effect: write
      questions:
      - How do I invite a teammate to my organization by email?
      - Can an invite on the unversioned endpoint also put the person in a specific workspace?
      instructions:
      - text: Invite {email} to the organization with role {role}.
        slots:
          email: requestBody.email
          role: requestBody.role
      - text: Send an unversioned invite to {email} for workspace {workspace}.
        slots:
          email: requestBody.email
          workspace: requestBody.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/invites'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a user to the organization (core v1)
      effect: write
      questions:
      - Does a core v1 invite email the person a link to create their account?
      - Which organization role id do I need to invite someone through core v1?
      instructions:
      - text: Send a core v1 invite to {email} with organization role {role}.
        slots:
          email: requestBody.email
          role: requestBody.organizationRoleId
      - text: Email {email} an account-creation link and give them role {role}.
        slots:
          email: requestBody.email
          role: requestBody.organizationRoleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List organization roles
      effect: read
      questions:
      - Which organization roles can I assign to users?
      - Where do I find the role id to give a new user?
      instructions:
      - text: List the roles in my organization.
      - text: Show the first {count} organization roles.
        slots:
          count: query.first
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List or find organization users (core v1)
      effect: read
      questions:
      - Can I look up an organization user by email address?
      - How many users are in my organization, according to core v1?
      instructions:
      - text: Find the organization user with email {email}.
        slots:
          email: query.email
      - text: List organization users via core v1, {count} per page.
        slots:
          count: query.first
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization user without an invite
      effect: write
      questions:
      - How do I add a user when my organization uses SSO and I don't want an invite email sent?
      - Can I create an organization user directly with a name, email and role?
      instructions:
      - text: Create organization user {name} with email {email} and role {role}, no invitation.
        slots:
          name: requestBody.name
          email: requestBody.email
          role: requestBody.organizationRoleId
      - text: Add SSO user {email} named {name} as role {role}.
        slots:
          email: requestBody.email
          name: requestBody.name
          role: requestBody.organizationRoleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization user by id
      effect: read
      questions:
      - What details does Tray hold for a specific organization user?
      - Can I fetch one user record if I know its id?
      instructions:
      - text: Get organization user {user}.
        slots:
          user: path.userId
      - text: Show the profile of user id {user}.
        slots:
          user: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/users/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization user
      effect: destructive
      questions:
      - Can I delete someone from my organization by user id?
      - Which call removes an organization user entirely?
      instructions:
      - text: Delete organization user {user}.
        slots:
          user: path.userId
      - text: Remove user {user} from the organization entirely.
        slots:
          user: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/users/{userId}/roles'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a user's organization role
      effect: write
      questions:
      - How do I promote or demote a user's role across the organization?
      - Can I change someone's organization-level role without touching workspace roles?
      instructions:
      - text: Change the organization role of user {user} to {role}.
        slots:
          user: path.userId
          role: requestBody.roleId
      - text: Set user {user}'s org-wide role to {role}.
        slots:
          user: path.userId
          role: requestBody.roleId
      method: generated
      generated: '2026-09-26'