# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clix So Clix External Service API
  version: 1.0.0
extends: openapi/clix-so-clixexternalservice-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: 11
- target: $.paths['/api/v1/devices'].post
  update:
    x-apievangelist-phrasing:
      intent: Register or update app devices
      effect: write
      questions:
      - Can I register new app installs as devices in Clix so they can receive messages?
      - What happens if I send a device record that already exists, does it get updated?
      - Is there a way to upsert several devices in one request?
      instructions:
      - text: 'Register these devices with Clix, updating any that already exist: {devices}.'
        slots:
          devices: requestBody.devices
      - text: Upsert the device records for my latest app installs.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/devices/{deviceId}/user/project-user-id'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a device to a project user ID
      effect: write
      questions:
      - How do I associate a device with my own user ID after someone logs in?
      - Can I change which project user ID a specific device belongs to?
      instructions:
      - text: Link device {deviceId} to project user ID {project_user_id}.
        slots:
          deviceId: path.deviceId
          project_user_id: requestBody.project_user_id
      - text: Set the project user ID on device {deviceId} to the logged-in user's ID.
        slots:
          deviceId: path.deviceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/devices/{deviceId}/user/properties'].post
  update:
    x-apievangelist-phrasing:
      intent: Set user properties via a device ID
      effect: write
      questions:
      - Can I update a user's properties when I only know their device ID?
      - How do I attach attributes like plan or locale to the user behind a device?
      instructions:
      - text: Set properties {properties} on the user linked to device {deviceId}.
        slots:
          properties: requestBody.properties
          deviceId: path.deviceId
      - text: Upsert the user properties for whoever owns device {deviceId}.
        slots:
          deviceId: path.deviceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/events'].post
  update:
    x-apievangelist-phrasing:
      intent: Track user events
      effect: write
      questions:
      - How do I send in-app events like purchases or sign-ups to Clix?
      - Can I record a batch of user events in a single call?
      instructions:
      - text: 'Record these tracking events: {events}.'
        slots:
          events: requestBody.events
      - text: Log a batch of user activity events from today's sessions.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check that the service is up
      effect: read
      questions:
      - Is the external service API currently healthy and reachable?
      - What endpoint can I ping to verify the API is responding?
      instructions:
      - text: Run a health check against the API.
      - text: Ping the service to confirm it is up before sending traffic.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/messages:send'].post
  update:
    x-apievangelist-phrasing:
      intent: Send push notifications to devices
      effect: write
      questions:
      - How do I send a push notification to a user's phone?
      - How many push notifications should I include per request?
      - Can one call push messages to several user devices at once?
      instructions:
      - text: 'Send these push notifications: {push_notifications}.'
        slots:
          push_notifications: requestBody.push_notifications
      - text: Push a notification to each of these user devices, keeping it under 500 per call.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user
      effect: write
      questions:
      - How do I create a new user record keyed by my own user ID?
      - Can I set initial properties when I first create a user?
      instructions:
      - text: Create a new user with project user ID {project_user_id}.
        slots:
          project_user_id: requestBody.project_user_id
      - text: Create user {project_user_id} with starting properties {properties}.
        slots:
          project_user_id: requestBody.project_user_id
          properties: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/users/{project_user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a user
      effect: destructive
      questions:
      - How do I permanently remove a user and all their data?
      - Does deleting a user also wipe the data associated with them?
      instructions:
      - text: Delete user {project_user_id} and all of their data.
        slots:
          project_user_id: path.project_user_id
      - text: Permanently erase the user with project user ID {project_user_id}.
        slots:
          project_user_id: path.project_user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/users/{project_user_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing user's properties
      effect: write
      questions:
      - How do I change properties on a user I already created, using their project user ID?
      - Can I modify just a few attributes of an existing user?
      instructions:
      - text: Update existing user {project_user_id} with properties {properties}.
        slots:
          project_user_id: path.project_user_id
          properties: requestBody.properties
      - text: Patch the profile of user {project_user_id} with their new subscription tier.
        slots:
          project_user_id: path.project_user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/live-activities:start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start iOS Live Activities on devices
      effect: write
      questions:
      - How do I start an iOS Live Activity remotely using Push to Start?
      - Can I launch Live Activities on several users' iPhones in one request?
      instructions:
      - text: 'Start these Live Activities on user devices: {live_activities}.'
        slots:
          live_activities: requestBody.live_activities
      - text: Kick off a delivery-tracking Live Activity on the customer's iPhone.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/campaigns/{campaign_id}:trigger'].post
  update:
    x-apievangelist-phrasing:
      intent: Trigger an API-triggered campaign
      effect: write
      questions:
      - How do I fire an API-triggered campaign from my backend?
      - Can I pass personalization properties when triggering a campaign?
      - Is it possible to target a specific audience when a campaign is triggered?
      instructions:
      - text: Trigger campaign {campaign_id}.
        slots:
          campaign_id: path.campaign_id
      - text: Trigger campaign {campaign_id} for audience {audience} with personalization {properties}.
        slots:
          campaign_id: path.campaign_id
          audience: requestBody.audience
          properties: requestBody.properties
      method: generated
      generated: '2026-10-01'