API Evangelist conversational phrasing for Common Room Activities API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Common Room Activities API
  version: 1.0.0
extends: openapi/common-room-activities-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: 7
- target: $.paths['/source/{destinationSourceId}/activity'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or update an activity in an API signal source
      effect: write
      questions:
      - How do I push activity from my own system into Common Room?
      - Can I edit an activity I previously sent by reusing its ID and type?
      - Is it possible to thread an activity as a reply to another activity?
      instructions:
      - text: Add activity {id} of type {activityType} by {user} to source {destinationSourceId}.
        slots:
          id: requestBody.id
          activityType: requestBody.activityType
          user: requestBody.user
          destinationSourceId: path.destinationSourceId
      - text: Record a {activityType} activity {id} titled {activityTitle} for {user} in source {destinationSourceId}, linking to {url}.
        slots:
          activityType: requestBody.activityType
          id: requestBody.id
          activityTitle: requestBody.activityTitle
          user: requestBody.user
          destinationSourceId: path.destinationSourceId
          url: requestBody.url
      - text: Update activity {id} ({activityType}) by {user} in source {destinationSourceId} with content {content}.
        slots:
          id: requestBody.id
          activityType: requestBody.activityType
          user: requestBody.user
          destinationSourceId: path.destinationSourceId
          content: requestBody.content
      method: generated
      generated: '2026-10-01'
- target: $.paths['/activityTypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List the accepted activity types
      effect: read
      questions:
      - What activity types are accepted when sending activity?
      - Which values can I use for an activity's type?
      instructions:
      - text: List all activity types.
      - text: Show me the valid activity type values.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/activities/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one activity by its ID
      effect: read
      questions:
      - Can I pull up a single activity if I know its a_ ID?
      - What extra columns, like content or participant count, can I include when fetching one activity?
      instructions:
      - text: Get activity {id}.
        slots:
          id: path.id
      - text: Fetch activity {id} including the columns {cols}.
        slots:
          id: path.id
          cols: query.cols
      method: generated
      generated: '2026-10-01'
- target: $.paths['/activities'].get
  update:
    x-apievangelist-phrasing:
      intent: List activities with filters and paging
      effect: read
      questions:
      - How do I page through all the activity recorded in our community?
      - Can I see only the activities from one contact or one organization?
      - Is there a way to limit activities to a date range?
      instructions:
      - text: List the activities for contact {contactId}.
        slots:
          contactId: query.contactId
      - text: List activities at organization {organizationId} between {startDate} and {endDate}.
        slots:
          organizationId: query.organizationId
          startDate: query.startDate
          endDate: query.endDate
      - text: Show the next {limit} activities after cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/activity-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List activity type IDs with display names
      effect: read
      questions:
      - What human-readable name goes with each activity type ID returned on activities?
      - Which activity type identifiers show up in the activities list, and what do they mean?
      instructions:
      - text: List activity type identifiers alongside their display names.
      - text: Translate the activity type IDs from the activities list into readable names.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/activity-categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List the community's activity categories
      effect: read
      questions:
      - What category labels are used to group activities in our community?
      - Which activity categories can I expect to see?
      instructions:
      - text: List all activity category labels.
      - text: Show me the categories activities are grouped into.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/activity-sentiment'].get
  update:
    x-apievangelist-phrasing:
      intent: List activity sentiment labels
      effect: read
      questions:
      - What sentiment classifications does Common Room apply to activity?
      - Which sentiment labels can an activity be tagged with, positive or negative?
      instructions:
      - text: List the activity sentiment labels.
      - text: Show every sentiment classification used for activities.
      method: generated
      generated: '2026-10-01'