# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Matomo Reporting API for plugin Users Manager API
  version: 1.0.0
extends: openapi/matomo-usersmanager-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: 32
- target: $.paths['/index.php?module=API&method=UsersManager.getAvailableRoles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the roles a user can be given
      effect: read
      questions:
      - What roles can I assign to users in Matomo?
      - Which access roles exist besides view and admin?
      instructions:
      - text: List every role available for user access.
      - text: Show me the role options I can pick when granting site access.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getAvailableCapabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: List the capabilities that can be granted
      effect: read
      questions:
      - Which extra capabilities can be layered on top of a user's role?
      - What capabilities are available to grant users?
      instructions:
      - text: List all available user capabilities.
      - text: Show the capability names I can add to a user.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.setUserPreference'].get
  update:
    x-apievangelist-phrasing:
      intent: Set a preference for a user
      effect: write
      questions:
      - Can I change a user's saved preference, like their default report, through the API?
      - How do I store a user preference value for someone else's login?
      instructions:
      - text: Set preference {preferenceName} to {preferenceValue} for user {userLogin}.
        slots:
          preferenceName: query.preferenceName
          preferenceValue: query.preferenceValue
          userLogin: query.userLogin
      - text: Change {userLogin}'s {preferenceName} setting to {preferenceValue}.
        slots:
          userLogin: query.userLogin
          preferenceName: query.preferenceName
          preferenceValue: query.preferenceValue
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUserPreference'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a user's preference value
      effect: read
      questions:
      - What value does a user currently have stored for a given preference?
      - Can I check my own saved preference without naming a login?
      instructions:
      - text: Get the value of preference {preferenceName} for user {userLogin}.
        slots:
          preferenceName: query.preferenceName
          userLogin: query.userLogin
      - text: Read my current {preferenceName} preference.
        slots:
          preferenceName: query.preferenceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsersPlusRole'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's users with their roles
      effect: read
      questions:
      - Who has access to this website and what role does each person have?
      - Can I filter a site's user list by access level or invite status?
      - Is there a way to search and page through users of one site?
      instructions:
      - text: List users and their roles for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show users on site {idSite} with {filter_access} access matching {filter_search}.
        slots:
          idSite: query.idSite
          filter_access: query.filter_access
          filter_search: query.filter_search
      - text: List pending-status users for site {idSite}, {limit} at a time.
        slots:
          idSite: query.idSite
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsers'].get
  update:
    x-apievangelist-phrasing:
      intent: List users visible to me
      effect: read
      questions:
      - Which user accounts can I see with my access?
      - Can I fetch full details for several specific logins at once?
      instructions:
      - text: List all user accounts I can see.
      - text: Get user details for logins {userLogins}.
        slots:
          userLogins: query.userLogins
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsersLogin'].get
  update:
    x-apievangelist-phrasing:
      intent: List the login names of visible users
      effect: read
      questions:
      - Can I get just the usernames of everyone, without their full details?
      - What login names exist that I'm allowed to see?
      instructions:
      - text: List only the login names of all users I can see.
      - text: Give me a plain list of usernames.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsersSitesFromAccess'].get
  update:
    x-apievangelist-phrasing:
      intent: Map users to sites for one access level
      effect: read
      questions:
      - For each user, which sites do they hold admin access on?
      - Which site IDs does every user have a given access level for?
      instructions:
      - text: For access level {access}, list each user with the site IDs where they have it.
        slots:
          access: query.access
      - text: Map every user to the sites where they hold {access} access.
        slots:
          access: query.access
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsersAccessFromSite'].get
  update:
    x-apievangelist-phrasing:
      intent: Show each user's access level on a site
      effect: read
      questions:
      - What access level does each user have on this one website?
      - Can I see a login-to-access map for a single site?
      instructions:
      - text: Show the access entry each user has on site {idSite}.
        slots:
          idSite: query.idSite
      - text: Map logins to their access level for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsersWithSiteAccess'].get
  update:
    x-apievangelist-phrasing:
      intent: Find users with a given access on a site
      effect: read
      questions:
      - Who are the admins on this particular website?
      - Which users have view-only access to a specific site?
      instructions:
      - text: List users who have {access} access to site {idSite}.
        slots:
          access: query.access
          idSite: query.idSite
      - text: Find everyone holding {access} on site {idSite}.
        slots:
          access: query.access
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getSitesAccessFromUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's raw site access entries
      effect: read
      questions:
      - Which websites can a given user access, and at what level?
      - Can I get the unfiltered access list assigned to one login?
      instructions:
      - text: Get the raw site access entries for user {userLogin}.
        slots:
          userLogin: query.userLogin
      - text: List every site and access level assigned to {userLogin}, unpaginated.
        slots:
          userLogin: query.userLogin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getSitesAccessForUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through a user's site access with filters
      effect: read
      questions:
      - Can I search a non-superuser's site permissions by site name?
      - How do I page through a long list of sites one user can access?
      instructions:
      - text: Show sites user {userLogin} can access matching {filter_search}.
        slots:
          userLogin: query.userLogin
          filter_search: query.filter_search
      - text: List sites where {userLogin} has {filter_access} access, {limit} per page.
        slots:
          userLogin: query.userLogin
          filter_access: query.filter_access
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's details by login
      effect: read
      questions:
      - What account details are stored for a particular username?
      - Can I look up one user's metadata by their login?
      instructions:
      - text: Get the account details for user {userLogin}.
        slots:
          userLogin: query.userLogin
      - text: Show me {userLogin}'s user profile metadata.
        slots:
          userLogin: query.userLogin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUserByEmail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's details by email
      effect: read
      questions:
      - Can I pull up a user's account details using only their email address?
      - What does the user record look like for a given email?
      instructions:
      - text: Get the full user record for email {userEmail}.
        slots:
          userEmail: query.userEmail
      - text: Show account metadata for the user with email {userEmail}.
        slots:
          userEmail: query.userEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.addUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Create a user account with a password
      effect: write
      questions:
      - How do I create a new user account with a password I set myself?
      - Can a new user be given access to a starting website when the account is created?
      instructions:
      - text: Create user {userLogin} with email {email} and password {password}.
        slots:
          userLogin: query.userLogin
          email: query.email
          password: query.password
      - text: Add account {userLogin} ({email}, password {password}) with initial access to site {initialIdSite}.
        slots:
          userLogin: query.userLogin
          email: query.email
          password: query.password
          initialIdSite: query.initialIdSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.inviteUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Invite a new user by email
      effect: write
      questions:
      - Can I send someone an email invitation instead of setting their password?
      - How long does an invitation stay valid, and can I change it?
      instructions:
      - text: Invite {email} as user {userLogin}.
        slots:
          email: query.email
          userLogin: query.userLogin
      - text: Invite {userLogin} at {email} to site {initialIdSite} with the invite expiring in {expiryInDays} days.
        slots:
          userLogin: query.userLogin
          email: query.email
          initialIdSite: query.initialIdSite
          expiryInDays: query.expiryInDays
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.setSuperUserAccess'].get
  update:
    x-apievangelist-phrasing:
      intent: Grant or revoke super user access
      effect: destructive
      questions:
      - How do I make a user a super user?
      - What happens to a user's existing permissions when they become a super user?
      instructions:
      - text: Set super user access for {userLogin} to {hasSuperUserAccess}.
        slots:
          userLogin: query.userLogin
          hasSuperUserAccess: query.hasSuperUserAccess
      - text: Remove super user rights from {userLogin} by setting {hasSuperUserAccess}.
        slots:
          userLogin: query.userLogin
          hasSuperUserAccess: query.hasSuperUserAccess
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.hasSuperUserAccess'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if I am a super user
      effect: read
      questions:
      - Does the token I'm using have super user rights?
      - Am I signed in with super user access right now?
      instructions:
      - text: Check whether my current account has super user access.
      - text: Tell me if this API token belongs to a super user.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUsersHavingSuperUserAccess'].get
  update:
    x-apievangelist-phrasing:
      intent: List all super users
      effect: read
      questions:
      - Who are all the super users on this instance?
      - Which accounts currently have full super user rights?
      instructions:
      - text: List every user that has super user access.
      - text: Show me all super user accounts.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.updateUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Change a user's email or password
      effect: write
      questions:
      - How do I change an existing user's email address?
      - Can I reset another user's password through the API?
      instructions:
      - text: Change the email of user {userLogin} to {email}.
        slots:
          userLogin: query.userLogin
          email: query.email
      - text: Set a new password {password} for existing user {userLogin}.
        slots:
          password: query.password
          userLogin: query.userLogin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.deleteUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How do I permanently remove a user and all their site access?
      - Does deleting a user also remove their access assignments?
      instructions:
      - text: Delete user account {userLogin}.
        slots:
          userLogin: query.userLogin
      - text: Remove {userLogin} and all of their access entries.
        slots:
          userLogin: query.userLogin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.logoutUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Sign a user out of all sessions
      effect: destructive
      questions:
      - Can I force a user to be logged out everywhere?
      - Is there a way to end all active sessions for a compromised account?
      instructions:
      - text: Sign {userLogin} out of all active sessions.
        slots:
          userLogin: query.userLogin
      - text: Force-logout user {userLogin} on every device.
        slots:
          userLogin: query.userLogin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.userExists'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a login name exists
      effect: read
      questions:
      - Is a particular username already taken?
      - Can I check whether a login exists before creating it?
      instructions:
      - text: Check whether login {userLogin} exists.
        slots:
          userLogin: query.userLogin
      - text: Tell me if username {userLogin} is already in use.
        slots:
          userLogin: query.userLogin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.userEmailExists'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if an email belongs to a user
      effect: read
      questions:
      - Is there already an account registered with this email?
      - Can I verify an email isn't in use before inviting someone?
      instructions:
      - text: Check whether any user has email {userEmail}.
        slots:
          userEmail: query.userEmail
      - text: Confirm whether {userEmail} is already registered.
        slots:
          userEmail: query.userEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.getUserLoginFromUserEmail'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a user's login from their email
      effect: read
      questions:
      - What's the username for the person with this email address?
      - Can I translate an email into a login name?
      instructions:
      - text: Find the login name for email {userEmail}.
        slots:
          userEmail: query.userEmail
      - text: Return only the username tied to {userEmail}.
        slots:
          userEmail: query.userEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.setUserAccess'].get
  update:
    x-apievangelist-phrasing:
      intent: Set a user's access level on sites
      effect: write
      questions:
      - How do I give a user admin access to several websites at once?
      - Can I change someone from view to write access on a site?
      instructions:
      - text: Give {userLogin} {access} access to sites {idSites}.
        slots:
          userLogin: query.userLogin
          access: query.access
          idSites: query.idSites
      - text: Set the role of {userLogin} on site {idSites} to {access}.
        slots:
          userLogin: query.userLogin
          idSites: query.idSites
          access: query.access
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.addCapabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Grant capabilities to a user on sites
      effect: write
      questions:
      - Can I let a view-only user also publish live widgets or edit tags without making them admin?
      - How do I add an extra capability for a user on specific sites?
      instructions:
      - text: Grant capabilities {capabilities} to {userLogin} on sites {idSites}.
        slots:
          capabilities: query.capabilities
          userLogin: query.userLogin
          idSites: query.idSites
      - text: Add the {capabilities} capability for {userLogin} on site {idSites}.
        slots:
          capabilities: query.capabilities
          userLogin: query.userLogin
          idSites: query.idSites
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.removeCapabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Remove capabilities from a user on sites
      effect: destructive
      questions:
      - How do I take a capability away from a user without changing their role?
      - Can I revoke an extra capability on only some sites?
      instructions:
      - text: Revoke capabilities {capabilities} from {userLogin} on sites {idSites}.
        slots:
          capabilities: query.capabilities
          userLogin: query.userLogin
          idSites: query.idSites
      - text: Take {capabilities} away from {userLogin} for site {idSites}.
        slots:
          capabilities: query.capabilities
          userLogin: query.userLogin
          idSites: query.idSites
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.createAppSpecificTokenAuth'].get
  update:
    x-apievangelist-phrasing:
      intent: Create an app-specific API token
      effect: write
      questions:
      - How do I generate a new auth token for an integration?
      - Can an API token be set to expire after a number of hours or on a date?
      - Can I restrict a new token so it only works over secure POST requests?
      instructions:
      - text: Create a token for {userLogin} described as {description}, confirming with password {passwordConfirmation}.
        slots:
          userLogin: query.userLogin
          description: query.description
          passwordConfirmation: query.passwordConfirmation
      - text: Generate a token {description} for {userLogin} that expires on {expireDate}; my password is {passwordConfirmation}.
        slots:
          description: query.description
          userLogin: query.userLogin
          expireDate: query.expireDate
          passwordConfirmation: query.passwordConfirmation
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.newsletterSignup'].get
  update:
    x-apievangelist-phrasing:
      intent: Sign me up for the newsletter
      effect: write
      questions:
      - Can I subscribe my account to the product newsletter via the API?
      - Is there a call to opt the current user into newsletter emails?
      instructions:
      - text: Sign my account up for the newsletter.
      - text: Subscribe the current user to newsletter updates.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.resendInvite'].get
  update:
    x-apievangelist-phrasing:
      intent: Resend a pending user's invitation email
      effect: write
      questions:
      - Someone never got their invite email, can I send it again?
      - Can I extend the expiry when re-sending an invitation?
      instructions:
      - text: Resend the invitation email to pending user {userLogin}.
        slots:
          userLogin: query.userLogin
      - text: Email {userLogin} their invite again, valid for {expiryInDays} days.
        slots:
          userLogin: query.userLogin
          expiryInDays: query.expiryInDays
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UsersManager.generateInviteLink'].get
  update:
    x-apievangelist-phrasing:
      intent: Generate an invite link for a pending user
      effect: write
      questions:
      - Can I get an invitation link to share myself instead of emailing it?
      - What's a way to produce a fresh invite URL for someone who hasn't accepted yet?
      instructions:
      - text: Generate a new invite link for pending user {userLogin}.
        slots:
          userLogin: query.userLogin
      - text: Give me a shareable invite URL for {userLogin} that expires in {expiryInDays} days.
        slots:
          userLogin: query.userLogin
          expiryInDays: query.expiryInDays
      method: generated
      generated: '2026-10-01'