# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for HERE Tracking Users API
  version: 1.0.0
extends: openapi/here-users-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: 6
- target: $.paths['/users/v2/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the Users service health
      effect: read
      questions:
      - Is the HERE Tracking Users service up right now?
      - Can I ping the Users service before sending it requests?
      instructions:
      - text: Check the health of the Users service.
      - text: Tell me whether the Users service is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/v2/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Users service version
      effect: read
      questions:
      - What version of the Users service is deployed?
      - Which build of the Users service am I talking to?
      instructions:
      - text: Get the version of the Users service.
      - text: Show me which Users service version is running.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/v2/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List devices claimed by a project
      effect: read
      questions:
      - Which devices has my project claimed?
      - Can I page through all claimed devices in a project?
      instructions:
      - text: List devices claimed by project {projectId}.
        slots:
          projectId: query.projectId
      - text: Show {count} claimed devices per page for project {projectId}.
        slots:
          count: query.count
          projectId: query.projectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/v2/login'].post
  update:
    x-apievangelist-phrasing:
      intent: Log a user in and get an access token
      effect: write
      questions:
      - How do I get a user access token with an email and password?
      - Can I request a specific realm when logging a user in?
      instructions:
      - text: Log in {email} with password {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      - text: Get a user token for {email} with password {password} in realm {realm}.
        slots:
          email: requestBody.email
          password: requestBody.password
          realm: requestBody.realm
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/v2/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh an expired user access token
      effect: write
      questions:
      - My user access token expired; can I renew it without logging in again?
      - What do I need to refresh a user token?
      instructions:
      - text: Refresh access token {accessToken} using refresh token {refreshToken}.
        slots:
          accessToken: requestBody.accessToken
          refreshToken: requestBody.refreshToken
      - text: Renew my user session with refresh token {refreshToken}.
        slots:
          refreshToken: requestBody.refreshToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/v2/tokenExchange'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange a user token for a project-scoped one
      effect: write
      questions:
      - How do I get a user token scoped to one project?
      - Can I trade my access token for a narrower scope?
      instructions:
      - text: Exchange token {accessToken} for scope {scope}.
        slots:
          accessToken: requestBody.accessToken
          scope: requestBody.scope
      - text: Get a project-scoped token for scope {scope}.
        slots:
          scope: requestBody.scope
      method: generated
      generated: '2026-10-01'