# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Controlup Events API
  version: 1.0.0
extends: openapi/controlup-events-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: 5
- target: $.paths['/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List System Events log entries
      effect: read
      questions:
      - What alerts, actions and configuration changes appear in the System Events log?
      - Can I filter and sort system events with query-string filters?
      instructions:
      - text: List the latest entries from the System Events log.
      - text: Show {size} system events per page, page {page}.
        slots:
          page: query.page
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Query System Events with an OpenSearch body
      effect: read
      questions:
      - Can I send an OpenSearch query in the request body to search system events?
      - How do I run a complex search over the System Events log that doesn't fit in query parameters?
      instructions:
      - text: Search the System Events log with the OpenSearch query I provide.
      - text: Run an OpenSearch body query against system events for configuration changes.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/organizations/{orgId}/events'].post
  update:
    x-apievangelist-phrasing:
      intent: List organization events in a time range
      effect: read
      questions:
      - Which events happened in my organization during a specific time window?
      - Can I return only chosen event fields and page with a cursor?
      instructions:
      - text: List events in organization {orgId} from {timeFrom} to {timeTo}, {limit} per page, returning fields {fields}.
        slots:
          fields: requestBody.fields
          limit: requestBody.limit
          orgId: path.orgId
          timeFrom: requestBody.timeFrom
          timeTo: requestBody.timeTo
      - text: Get the next page of organization {orgId} events using cursor {cursor}, {limit} per page, fields {fields}, {timeFrom} to {timeTo}.
        slots:
          cursor: requestBody.cursor
          fields: requestBody.fields
          limit: requestBody.limit
          orgId: path.orgId
          timeFrom: requestBody.timeFrom
          timeTo: requestBody.timeTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/organizations/{orgId}/events/total'].get
  update:
    x-apievangelist-phrasing:
      intent: Count unique values of an event field
      effect: read
      questions:
      - How many distinct users or devices generated events in a time range?
      - Can I count unique values of one event attribute?
      instructions:
      - text: Count unique values of {field} in organization {orgId} events from {timeFrom} to {timeTo}.
        slots:
          field: query.field
          orgId: path.orgId
          timeFrom: query.timeFrom
          timeTo: query.timeTo
      - text: Tell me the cardinality of {field} across events in {orgId} between {timeFrom} and {timeTo}.
        slots:
          field: query.field
          orgId: path.orgId
          timeFrom: query.timeFrom
          timeTo: query.timeTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/organizations/{orgId}/events/{eventId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a single event
      effect: read
      questions:
      - What are the full details of one specific event?
      - Can I look up an event by its UUID?
      instructions:
      - text: Get event {eventId} in organization {orgId}.
        slots:
          eventId: path.eventId
          orgId: path.orgId
      - text: Show everything recorded for event {eventId} in {orgId}.
        slots:
          eventId: path.eventId
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'