# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana Security Timeline API
  version: 1.0.0
extends: openapi/elk-stack-security-timeline-api-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: 17
- target: $.paths['/api/note'].get
  update:
    x-apievangelist-phrasing:
      intent: List investigation notes
      effect: read
      questions:
      - What notes have analysts left on a particular alert or event document?
      - Can I find only the notes I created myself?
      - Which notes are attached to a given saved Timeline?
      instructions:
      - text: Get the notes attached to documents {documentIds}.
        slots:
          documentIds: query.documentIds
      - text: List notes on Timeline {savedObjectIds}, sorted by {sortField}.
        slots:
          savedObjectIds: query.savedObjectIds
          sortField: query.sortField
      - text: Search notes for {search} created by {createdByFilter}.
        slots:
          search: query.search
          createdByFilter: query.createdByFilter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/note'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one or more Timeline notes
      effect: destructive
      questions:
      - How do I remove a note I left on a Timeline investigation?
      - Can I delete several investigation notes in one request?
      instructions:
      - text: Delete the note I added to the investigation.
      - text: Remove these Timeline notes permanently.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/note'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add or edit a note on a Timeline or event
      effect: write
      questions:
      - How do I add a note to a Timeline or to an event in it?
      - Can I edit an existing investigation note if I know its ID?
      instructions:
      - text: Add note {note} to the Timeline.
        slots:
          note: requestBody.note
      - text: Update note {noteId} at version {version} to read {note}.
        slots:
          noteId: requestBody.noteId
          version: requestBody.version
          note: requestBody.note
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned_event'].patch
  update:
    x-apievangelist-phrasing:
      intent: Pin or unpin an event in a Timeline
      effect: write
      questions:
      - How do I pin an important event so it stays at the top of a Timeline?
      - Can I unpin an event I pinned earlier?
      instructions:
      - text: Pin event {eventId} in Timeline {timelineId}.
        slots:
          eventId: requestBody.eventId
          timelineId: requestBody.timelineId
      - text: Unpin event {eventId} from Timeline {timelineId} using pinned event {pinnedEventId}.
        slots:
          eventId: requestBody.eventId
          timelineId: requestBody.timelineId
          pinnedEventId: requestBody.pinnedEventId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a saved Timeline or template
      effect: read
      questions:
      - How do I load a saved Timeline investigation by its ID?
      - Can I fetch a Timeline template by its template ID?
      instructions:
      - text: Get the saved Timeline with ID {id}.
        slots:
          id: query.id
      - text: Fetch Timeline template {template_timeline_id}.
        slots:
          template_timeline_id: query.template_timeline_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Timeline or Timeline template
      effect: write
      questions:
      - How do I create a new Timeline for a security investigation?
      - Can I save a new Timeline as a reusable template instead?
      instructions:
      - text: Create a new Timeline from {timeline}.
        slots:
          timeline: requestBody.timeline
      - text: Create a {timelineType} Timeline with definition {timeline}.
        slots:
          timelineType: requestBody.timelineType
          timeline: requestBody.timeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete Timelines or templates
      effect: destructive
      questions:
      - How do I delete old Timeline investigations I no longer need?
      - Can I delete several Timelines and templates in one request?
      instructions:
      - text: Delete Timelines {savedObjectIds}.
        slots:
          savedObjectIds: requestBody.savedObjectIds
      - text: Remove the Timeline templates with saved object IDs {savedObjectIds}.
        slots:
          savedObjectIds: requestBody.savedObjectIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing Timeline
      effect: write
      questions:
      - How do I change the title or query of a Timeline I already saved?
      - Why does updating a Timeline require its current version?
      instructions:
      - text: Update Timeline {timelineId} at version {version} with {timeline}.
        slots:
          timelineId: requestBody.timelineId
          version: requestBody.version
          timeline: requestBody.timeline
      - text: Rename existing Timeline {timelineId} (version {version}) using changes {timeline}.
        slots:
          timelineId: requestBody.timelineId
          version: requestBody.version
          timeline: requestBody.timeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_copy'].post
  update:
    x-apievangelist-phrasing:
      intent: Duplicate a Timeline or template
      effect: write
      questions:
      - Can I make a copy of an existing Timeline to start a new investigation from it?
      - How do I duplicate a Timeline template?
      instructions:
      - text: Copy Timeline {timelineIdToCopy} with overrides {timeline}.
        slots:
          timelineIdToCopy: requestBody.timelineIdToCopy
          timeline: requestBody.timeline
      - text: Duplicate Timeline {timelineIdToCopy} into a new one defined by {timeline}.
        slots:
          timelineIdToCopy: requestBody.timelineIdToCopy
          timeline: requestBody.timeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_draft'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my current draft Timeline
      effect: read
      questions:
      - Where is the unsaved draft Timeline I was working on?
      - Can I retrieve my draft Timeline template separately from a regular draft?
      instructions:
      - text: Get my draft Timeline of type {timelineType}.
        slots:
          timelineType: query.timelineType
      - text: Show the current {timelineType} draft details.
        slots:
          timelineType: query.timelineType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_draft'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a clean draft Timeline
      effect: write
      questions:
      - How do I reset my draft Timeline to a blank one?
      - Can I start a fresh draft Timeline template?
      instructions:
      - text: Create a clean {timelineType} draft Timeline.
        slots:
          timelineType: requestBody.timelineType
      - text: Reset my draft to an empty {timelineType} Timeline.
        slots:
          timelineType: requestBody.timelineType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export Timelines to a file
      effect: read
      questions:
      - How do I export saved Timelines to an ndjson file for backup?
      - Can I export just a few selected Timelines?
      instructions:
      - text: Export Timelines {ids} to file {file_name}.
        slots:
          ids: requestBody.ids
          file_name: query.file_name
      - text: Export all Timelines into {file_name}.
        slots:
          file_name: query.file_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_favorite'].patch
  update:
    x-apievangelist-phrasing:
      intent: Favorite or unfavorite a Timeline
      effect: write
      questions:
      - How do I star a Timeline so it shows up in my favorites?
      - Can I favorite a Timeline template as well as a regular Timeline?
      instructions:
      - text: Favorite Timeline {timelineId} of type {timelineType}, template {templateTimelineId} version {templateTimelineVersion}.
        slots:
          timelineId: requestBody.timelineId
          timelineType: requestBody.timelineType
          templateTimelineId: requestBody.templateTimelineId
          templateTimelineVersion: requestBody.templateTimelineVersion
      - text: Toggle favorite on {timelineType} {timelineId} (template {templateTimelineId}, v{templateTimelineVersion}).
        slots:
          timelineType: requestBody.timelineType
          timelineId: requestBody.timelineId
          templateTimelineId: requestBody.templateTimelineId
          templateTimelineVersion: requestBody.templateTimelineVersion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import Timelines from a file
      effect: write
      questions:
      - How do I import Timelines exported from another Kibana?
      - Can imported Timelines be marked immutable?
      instructions:
      - text: Import Timelines from file {file}.
        slots:
          file: requestBody.file
      - text: Import {file} as Timelines with immutable set to {isImmutable}.
        slots:
          file: requestBody.file
          isImmutable: requestBody.isImmutable
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/_prepackaged'].post
  update:
    x-apievangelist-phrasing:
      intent: Install Elastic prebuilt Timeline templates
      effect: write
      questions:
      - How do I install the prepackaged Timeline templates that ship with Elastic Security?
      - Can I update prebuilt Timelines that are already installed?
      instructions:
      - text: Install prepackaged Timelines {timelinesToInstall} and update {timelinesToUpdate} from {prepackagedTimelines}.
        slots:
          timelinesToInstall: requestBody.timelinesToInstall
          timelinesToUpdate: requestBody.timelinesToUpdate
          prepackagedTimelines: requestBody.prepackagedTimelines
      - text: Load the prebuilt set {prepackagedTimelines}, installing {timelinesToInstall} and refreshing {timelinesToUpdate}.
        slots:
          prepackagedTimelines: requestBody.prepackagedTimelines
          timelinesToInstall: requestBody.timelinesToInstall
          timelinesToUpdate: requestBody.timelinesToUpdate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timeline/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Resolve a Timeline ID after space migration
      effect: read
      questions:
      - How do I resolve a Timeline whose ID may have changed after a space migration?
      - Can I tell whether a Timeline link points to an alias or a conflicting object?
      instructions:
      - text: Resolve Timeline {id} and report its outcome.
        slots:
          id: query.id
      - text: Resolve template Timeline {template_timeline_id} to its current saved object.
        slots:
          template_timeline_id: query.template_timeline_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/timelines'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved Timelines and templates
      effect: read
      questions:
      - What saved Timelines exist in this space?
      - Can I list only my favorite Timelines?
      - Which Timeline templates are active?
      instructions:
      - text: List {timeline_type} Timelines sorted by {sort_field} {sort_order}.
        slots:
          timeline_type: query.timeline_type
          sort_field: query.sort_field
          sort_order: query.sort_order
      - text: Search saved Timelines for {search}.
        slots:
          search: query.search
      - text: Show only my favorite Timelines.
      method: generated
      generated: '2026-09-26'