# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana Markdowns API
  version: 1.0.0
extends: openapi/elk-stack-markdowns-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['/api/markdowns'].get
  update:
    x-apievangelist-phrasing:
      intent: List markdown library items
      effect: read
      questions:
      - What markdown items are saved in my Kibana markdown library?
      - Can I search the markdown library by text and page through the results?
      - Does listing the markdown library return each item's content or just titles?
      instructions:
      - text: List the items in my Kibana markdown library.
      - text: Search the markdown library for {query} and show page {page}.
        slots:
          query: query.query
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/markdowns'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a markdown library item
      effect: write
      questions:
      - How do I add a new reusable markdown snippet to the Kibana library?
      - Which fields are required when creating a markdown library item?
      instructions:
      - text: Create a markdown library item titled {title} with content {content}.
        slots:
          title: requestBody.title
          content: requestBody.content
      - text: Add a new markdown snippet called {title} described as {description}, with body {content}.
        slots:
          title: requestBody.title
          description: requestBody.description
          content: requestBody.content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/markdowns/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a markdown library item's full content
      effect: read
      questions:
      - How do I read the full markdown content of one saved library item?
      - Can I fetch a single markdown library item and its settings by its ID?
      instructions:
      - text: Show me the complete markdown library item {id}, including its content.
        slots:
          id: path.id
      - text: Open markdown item {id} so I can see its text before editing it.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/markdowns/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace or upsert a markdown library item
      effect: write
      questions:
      - How do I update the text of an existing markdown library item?
      - Does saving a markdown item under a new ID create it if it does not exist?
      - Can I change just the title of a markdown item, or must I resend the whole thing?
      instructions:
      - text: Replace markdown item {id} with title {title} and content {content}.
        slots:
          id: path.id
          title: requestBody.title
          content: requestBody.content
      - text: Upsert markdown library item {id} so it reads {content} under the title {title}.
        slots:
          id: path.id
          content: requestBody.content
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/markdowns/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a markdown library item
      effect: destructive
      questions:
      - How do I permanently remove a markdown snippet from the library?
      - Is deleting a markdown library item reversible?
      instructions:
      - text: Delete markdown library item {id}.
        slots:
          id: path.id
      - text: Permanently remove the markdown snippet with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'