# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for authentik Events API
  version: 1.0.0
extends: openapi/authentik-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: 33
- target: $.paths['/events/events/'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the audit event log
      effect: read
      questions:
      - Which login and admin events did a specific user trigger?
      - Can I filter the audit log by client IP address?
      - What events touched a particular model object, like one application?
      instructions:
      - text: List recent audit events.
      - text: Show events performed by user {username}.
        slots:
          username: query.username
      - text: List {action} events that came from IP {client_ip}.
        slots:
          action: query.action
          client_ip: query.client_ip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a custom audit event
      effect: write
      questions:
      - Can I write my own entry into the authentik event log?
      - What does it take to log a custom event with an action and app name?
      instructions:
      - text: Log a {action} event for app {app}.
        slots:
          action: requestBody.action
          app: requestBody.app
      - text: Record event {action} from app {app} with context {context}.
        slots:
          action: requestBody.action
          app: requestBody.app
          context: requestBody.context
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/{event_uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one audit event
      effect: read
      questions:
      - What exactly is recorded in a single event, including its context?
      - Where can I view one audit log entry by its UUID?
      instructions:
      - text: Show event {event_uuid}.
        slots:
          event_uuid: path.event_uuid
      - text: Get the full context of audit event {event_uuid}.
        slots:
          event_uuid: path.event_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/{event_uuid}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an audit event
      effect: write
      questions:
      - Can I overwrite an existing event record with a new action and app?
      - What must I send to fully replace a logged event?
      instructions:
      - text: Replace event {event_uuid} with action {action} and app {app}.
        slots:
          event_uuid: path.event_uuid
          action: requestBody.action
          app: requestBody.app
      - text: Overwrite event {event_uuid} as {action} from {app} with context {context}.
        slots:
          event_uuid: path.event_uuid
          action: requestBody.action
          app: requestBody.app
          context: requestBody.context
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/{event_uuid}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an audit event
      effect: destructive
      questions:
      - Can I remove a single entry from the event log?
      - What happens if I delete an audit event?
      instructions:
      - text: Delete event {event_uuid}.
        slots:
          event_uuid: path.event_uuid
      - text: Remove audit log entry {event_uuid} permanently.
        slots:
          event_uuid: path.event_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/{event_uuid}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit fields on an audit event
      effect: write
      questions:
      - Can I change just the expiry date of a logged event?
      - Is it possible to patch only the context of an existing event?
      instructions:
      - text: Set event {event_uuid} to expire at {expires}.
        slots:
          event_uuid: path.event_uuid
          expires: requestBody.expires
      - text: Update only the context of event {event_uuid} to {context}.
        slots:
          event_uuid: path.event_uuid
          context: requestBody.context
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/actions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List all event action types
      effect: read
      questions:
      - What kinds of actions can appear in the authentik event log?
      - Which event action names can I filter or alert on?
      instructions:
      - text: List every event action type.
      - text: Show the possible audit event actions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/export/'].post
  update:
    x-apievangelist-phrasing:
      intent: Export audit events to a file
      effect: write
      questions:
      - How do I download the event log as a file?
      - Can I export only the events for one user, and how do I know when the export is ready?
      instructions:
      - text: Export all audit events.
      - text: Start an export of events for user {username}.
        slots:
          username: query.username
      - text: Export {action} events from IP {client_ip} to a downloadable file.
        slots:
          action: query.action
          client_ip: query.client_ip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/stats/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get event counts over time steps
      effect: read
      questions:
      - Can I get event statistics bucketed into a set number of count steps?
      - What do aggregate counts look like for failed logins across time buckets?
      instructions:
      - text: Get event stats in {count_steps} steps.
        slots:
          count_steps: query.count_steps
      - text: Show {action} event stats split into {count_steps} steps.
        slots:
          action: query.action
          count_steps: query.count_steps
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/top_per_user/'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank users by event count
      effect: read
      questions:
      - Which users generate the most events of a given action?
      - Who are the top users by login count?
      instructions:
      - text: Show the top {top_n} users for {action} events.
        slots:
          top_n: query.top_n
          action: query.action
      - text: Group events by user and show the most active ones.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/events/volume/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get event volume over recent days
      effect: read
      questions:
      - How many events happened per day over the last few weeks?
      - Can I chart event volume for one action across a chosen number of days?
      instructions:
      - text: Show event volume for the last {history_days} days.
        slots:
          history_days: query.history_days
      - text: Chart the volume of {action} events.
        slots:
          action: query.action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/'].get
  update:
    x-apievangelist-phrasing:
      intent: List notifications
      effect: read
      questions:
      - Which notifications have I not seen yet?
      - Can I filter notifications by severity?
      instructions:
      - text: List my notifications.
      - text: Show notifications with seen set to {seen}.
        slots:
          seen: query.seen
      - text: List {severity} severity notifications.
        slots:
          severity: query.severity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/{uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one notification
      effect: read
      questions:
      - What does a specific notification say and which event triggered it?
      - Where can I open a single notification by its ID?
      instructions:
      - text: Show notification {uuid}.
        slots:
          uuid: path.uuid
      - text: Open notification {uuid} and tell me its event.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/{uuid}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a notification's fields
      effect: write
      questions:
      - Can I overwrite a notification's hyperlink, label and seen flag together?
      - What does a full replace of a notification look like?
      instructions:
      - text: Replace notification {uuid} with hyperlink {hyperlink} labeled {hyperlink_label}.
        slots:
          uuid: path.uuid
          hyperlink: requestBody.hyperlink
          hyperlink_label: requestBody.hyperlink_label
      - text: Overwrite notification {uuid}, setting seen to {seen}.
        slots:
          uuid: path.uuid
          seen: requestBody.seen
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/{uuid}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a notification
      effect: destructive
      questions:
      - Can I dismiss and delete a single notification?
      - Is there a way to remove one notification from my list for good?
      instructions:
      - text: Delete notification {uuid}.
        slots:
          uuid: path.uuid
      - text: Remove notification {uuid} permanently.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/{uuid}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark one notification as seen
      effect: write
      questions:
      - How do I mark a single notification as read?
      - Can I change just the link on one notification?
      instructions:
      - text: 'Mark notification {uuid} seen: {seen}.'
        slots:
          uuid: path.uuid
          seen: requestBody.seen
      - text: Change the link on notification {uuid} to {hyperlink}.
        slots:
          uuid: path.uuid
          hyperlink: requestBody.hyperlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/{uuid}/used_by/'].get
  update:
    x-apievangelist-phrasing:
      intent: See what uses a notification
      effect: read
      questions:
      - Which objects reference a given notification?
      - Does anything depend on this notification before I delete it?
      instructions:
      - text: List objects that use notification {uuid}.
        slots:
          uuid: path.uuid
      - text: Show what references notification {uuid}.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/notifications/mark_all_seen/'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark all my notifications as seen
      effect: write
      questions:
      - Is there a way to clear every unread notification at once?
      - Can I mark all of my notifications read in one call?
      instructions:
      - text: Mark all my notifications as seen.
      - text: Clear my entire unread notification list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/'].get
  update:
    x-apievangelist-phrasing:
      intent: List notification rules
      effect: read
      questions:
      - Which notification rules decide who gets alerted about events?
      - Can I find the rules that notify a particular group?
      instructions:
      - text: List all notification rules.
      - text: Show notification rules sending to group {destination_group__name}.
        slots:
          destination_group__name: query.destination_group__name
      - text: List notification rules with severity {severity}.
        slots:
          severity: query.severity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a notification rule
      effect: write
      questions:
      - How do I set up an alert that notifies a group when certain events happen?
      - Can a new notification rule send to the user who caused the event?
      instructions:
      - text: Create notification rule {name} notifying group {destination_group}.
        slots:
          name: requestBody.name
          destination_group: requestBody.destination_group
      - text: Add a {severity} rule called {name} that sends through transports {transports}.
        slots:
          severity: requestBody.severity
          name: requestBody.name
          transports: requestBody.transports
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/{pbm_uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a notification rule
      effect: read
      questions:
      - Which group and transports does one notification rule use?
      - Where can I view a single notification rule?
      instructions:
      - text: Show notification rule {pbm_uuid}.
        slots:
          pbm_uuid: path.pbm_uuid
      - text: Get the settings of alert rule {pbm_uuid}.
        slots:
          pbm_uuid: path.pbm_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/{pbm_uuid}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a notification rule
      effect: write
      questions:
      - Can I overwrite a notification rule's name, severity and transports in one go?
      - What does a full replacement of an alert rule need?
      instructions:
      - text: Replace notification rule {pbm_uuid} with name {name}.
        slots:
          pbm_uuid: path.pbm_uuid
          name: requestBody.name
      - text: Redefine rule {pbm_uuid} as {name} at severity {severity} via transports {transports}.
        slots:
          pbm_uuid: path.pbm_uuid
          name: requestBody.name
          severity: requestBody.severity
          transports: requestBody.transports
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/{pbm_uuid}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a notification rule
      effect: destructive
      questions:
      - How can I stop an alert rule from sending notifications?
      - Can I delete a notification rule I no longer need?
      instructions:
      - text: Delete notification rule {pbm_uuid}.
        slots:
          pbm_uuid: path.pbm_uuid
      - text: Remove alert rule {pbm_uuid}.
        slots:
          pbm_uuid: path.pbm_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/{pbm_uuid}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change some notification rule settings
      effect: write
      questions:
      - Can I change only the destination group of an existing rule?
      - Is it possible to bump just a rule's severity?
      instructions:
      - text: Send notification rule {pbm_uuid} to group {destination_group} instead.
        slots:
          pbm_uuid: path.pbm_uuid
          destination_group: requestBody.destination_group
      - text: Change the severity of rule {pbm_uuid} to {severity}.
        slots:
          pbm_uuid: path.pbm_uuid
          severity: requestBody.severity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/rules/{pbm_uuid}/used_by/'].get
  update:
    x-apievangelist-phrasing:
      intent: See what uses a notification rule
      effect: read
      questions:
      - What is still linked to an alert rule I want to retire?
      - Is anything bound to this alert rule?
      instructions:
      - text: List objects that use notification rule {pbm_uuid}.
        slots:
          pbm_uuid: path.pbm_uuid
      - text: Show what depends on alert rule {pbm_uuid}.
        slots:
          pbm_uuid: path.pbm_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/'].get
  update:
    x-apievangelist-phrasing:
      intent: List notification transports
      effect: read
      questions:
      - Which delivery channels, like email or webhook, are set up for notifications?
      - Can I find transports that post to a specific webhook URL?
      instructions:
      - text: List all notification transports.
      - text: Show transports in mode {mode}.
        slots:
          mode: query.mode
      - text: Find the transport posting to {webhook_url}.
        slots:
          webhook_url: query.webhook_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a notification transport
      effect: write
      questions:
      - How do I send authentik notifications to a webhook?
      - Can a new transport email alerts with a custom subject prefix?
      instructions:
      - text: Create a webhook transport {name} posting to {webhook_url}.
        slots:
          name: requestBody.name
          webhook_url: requestBody.webhook_url
      - text: Add transport {name} in mode {mode} with email subject prefix {email_subject_prefix}.
        slots:
          name: requestBody.name
          mode: requestBody.mode
          email_subject_prefix: requestBody.email_subject_prefix
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/{uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a notification transport
      effect: read
      questions:
      - What mode and webhook URL does a specific transport use?
      - Where can I view one notification transport's settings?
      instructions:
      - text: Show notification transport {uuid}.
        slots:
          uuid: path.uuid
      - text: Get the delivery settings of transport {uuid}.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/{uuid}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a notification transport
      effect: write
      questions:
      - Can I overwrite a transport's whole configuration at once?
      - What is required to fully replace a notification transport?
      instructions:
      - text: Replace transport {uuid} with name {name} in mode {mode}.
        slots:
          uuid: path.uuid
          name: requestBody.name
          mode: requestBody.mode
      - text: Redefine transport {uuid} as {name} sending to webhook {webhook_url}.
        slots:
          uuid: path.uuid
          name: requestBody.name
          webhook_url: requestBody.webhook_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/{uuid}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a notification transport
      effect: destructive
      questions:
      - How do I remove a webhook or email transport I no longer use?
      - Can I delete a single notification transport?
      instructions:
      - text: Delete notification transport {uuid}.
        slots:
          uuid: path.uuid
      - text: Remove delivery transport {uuid}.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/{uuid}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change some transport settings
      effect: write
      questions:
      - Can I change only the webhook URL on an existing transport?
      - Is it possible to make a transport send each notification just once?
      instructions:
      - text: Point transport {uuid} at webhook {webhook_url}.
        slots:
          uuid: path.uuid
          webhook_url: requestBody.webhook_url
      - text: Set send-once on transport {uuid} to {send_once}.
        slots:
          uuid: path.uuid
          send_once: requestBody.send_once
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/{uuid}/test/'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test notification
      effect: write
      questions:
      - How can I check a webhook or email transport actually delivers?
      - Can I fire an example notification through one transport?
      instructions:
      - text: Send a test notification through transport {uuid}.
        slots:
          uuid: path.uuid
      - text: Test delivery on transport {uuid}.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/events/transports/{uuid}/used_by/'].get
  update:
    x-apievangelist-phrasing:
      intent: See what uses a transport
      effect: read
      questions:
      - Which notification rules send through a given transport?
      - Does anything still depend on this delivery transport?
      instructions:
      - text: List objects that use transport {uuid}.
        slots:
          uuid: path.uuid
      - text: Show what references notification transport {uuid}.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'