# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Marketo Engage Rest User Management API
  version: 1.0.0
extends: openapi/adobe-suite-user-management-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: 12
- target: $.paths['/userservice/management/v1/users/allusers.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users
      effect: read
      questions:
      - How do I get a list of every user in my Marketo instance?
      - Can I page through user records with an offset and page size?
      instructions:
      - text: List all users.
      - text: Get {pageSize} user records starting at offset {pageOffset}.
        slots:
          pageSize: query.pageSize
          pageOffset: query.pageOffset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/invite.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a new user by email
      effect: write
      questions:
      - How can I send an email invitation to add a new user?
      - Can I create an API-only user or set an access expiry when inviting someone?
      instructions:
      - text: Invite {firstName} {lastName} at {emailAddress} with roles and workspaces {userRoleWorkspaces}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          emailAddress: requestBody.emailAddress
          userRoleWorkspaces: requestBody.userRoleWorkspaces
      - text: Send an invitation to {emailAddress} that expires at {expiresAt}.
        slots:
          emailAddress: requestBody.emailAddress
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/roles.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List available roles
      effect: read
      questions:
      - What roles can be assigned to users?
      - Where do I get the full list of role records?
      instructions:
      - text: List all roles.
      - text: Show me every role that exists in the instance.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/workspaces.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List workspaces
      effect: read
      questions:
      - Which workspaces exist that users can be given access to?
      - Can I retrieve all workspace records?
      instructions:
      - text: List all workspaces.
      - text: Show me the workspace records.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/delete.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete an active user
      effect: destructive
      questions:
      - How do I remove a user who has already accepted their invitation?
      - Can I permanently delete a user account?
      instructions:
      - text: Delete user {userid}.
        slots:
          userid: path.userid
      - text: Remove the active user account {userid}.
        slots:
          userid: path.userid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/invite/delete.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a pending user invitation
      effect: destructive
      questions:
      - Can I cancel an invitation that someone hasn't accepted yet?
      - How do I delete a pending user?
      instructions:
      - text: Delete the pending invitation for {userid}.
        slots:
          userid: path.userid
      - text: Withdraw the invite sent to user {userid} who hasn't accepted.
        slots:
          userid: path.userid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/update.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a user's attributes
      effect: write
      questions:
      - How do I change a user's name or email address?
      - Can I update when a user's access expires?
      instructions:
      - text: Change the email of user {userid} to {emailAddress}.
        slots:
          userid: path.userid
          emailAddress: requestBody.emailAddress
      - text: Set user {userid}'s access to expire at {expiresAt}.
        slots:
          userid: path.userid
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/roles.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's roles and workspaces
      effect: read
      questions:
      - Which roles and workspaces does a specific user have?
      - How can I audit what access one user has been granted?
      instructions:
      - text: Show the roles and workspaces for user {userid}.
        slots:
          userid: path.userid
      - text: List what access user {userid} holds across workspaces.
        slots:
          userid: path.userid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/roles/create.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add roles to a user
      effect: write
      questions:
      - How do I grant additional roles to an existing user?
      - Can I give a user a role in another workspace?
      instructions:
      - text: Add the roles {input} to user {userid}.
        slots:
          input: requestBody.input
          userid: path.userid
      - text: 'Grant user {userid} these role-workspace pairs: {input}.'
        slots:
          userid: path.userid
          input: requestBody.input
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/roles/delete.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove roles from a user
      effect: destructive
      questions:
      - How can I take a role away from a user?
      - Can I strip a user's access to a workspace by removing its role?
      instructions:
      - text: Remove the roles {input} from user {userid}.
        slots:
          input: requestBody.input
          userid: path.userid
      - text: 'Revoke these role assignments for user {userid}: {input}.'
        slots:
          userid: path.userid
          input: requestBody.input
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/user.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an active user by ID
      effect: read
      questions:
      - How do I look up one user's record by ID?
      - What details are stored on a single user?
      instructions:
      - text: Get user {userid}.
        slots:
          userid: path.userid
      - text: Show the user record for {userid}.
        slots:
          userid: path.userid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/userservice/management/v1/users/{userid}/invite.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pending invited user by ID
      effect: read
      questions:
      - Can I see the details of someone I invited who hasn't accepted yet?
      - How do I check a pending user's invitation record?
      instructions:
      - text: Get the pending invited user {userid}.
        slots:
          userid: path.userid
      - text: Show the invitation details for not-yet-accepted user {userid}.
        slots:
          userid: path.userid
      method: generated
      generated: '2026-09-26'