Elastic Stack · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Elastic Cloud Enterprise Comments API

6 actions 6 updates phrasing extends openapi/elk-stack-comments-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Elastic Stack's API. It is a proposal applied on top of the contract, not a document Elastic Stack publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 6

$.info

$.paths['/comments/{resource_type}/{resource_id}'].get

$.paths['/comments/{resource_type}/{resource_id}'].post

$.paths['/comments/{resource_type}/{resource_id}/{comment_id}'].get

$.paths['/comments/{resource_type}/{resource_id}/{comment_id}'].put

$.paths['/comments/{resource_type}/{resource_id}/{comment_id}'].delete

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elastic Cloud Enterprise Comments API
  version: 1.0.0
extends: openapi/elk-stack-comments-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['/comments/{resource_type}/{resource_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a resource
      effect: read
      questions:
      - What comments have been left on a deployment or other resource?
      - In what order are comments on a resource returned?
      instructions:
      - text: List comments on {resource_type} {resource_id}.
        slots:
          resource_type: path.resource_type
          resource_id: path.resource_id
      - text: Show every comment for {resource_type} resource {resource_id}, most recently modified first.
        slots:
          resource_type: path.resource_type
          resource_id: path.resource_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comments/{resource_type}/{resource_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a comment on a resource
      effect: write
      questions:
      - How do I leave a note on a platform resource for my team?
      - Can I comment on an allocator or deployment?
      instructions:
      - text: Add comment {message} to {resource_type} {resource_id}.
        slots:
          message: requestBody.message
          resource_type: path.resource_type
          resource_id: path.resource_id
      - text: Post a new comment saying {message} on {resource_type} resource {resource_id}.
        slots:
          message: requestBody.message
          resource_type: path.resource_type
          resource_id: path.resource_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comments/{resource_type}/{resource_id}/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single comment
      effect: read
      questions:
      - How do I read one specific comment on a resource?
      - What does comment X say and when was it last changed?
      instructions:
      - text: Get comment {comment_id} on {resource_type} {resource_id}.
        slots:
          comment_id: path.comment_id
          resource_type: path.resource_type
          resource_id: path.resource_id
      - text: Show comment {comment_id} from resource {resource_id} of type {resource_type}.
        slots:
          comment_id: path.comment_id
          resource_id: path.resource_id
          resource_type: path.resource_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comments/{resource_type}/{resource_id}/{comment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment
      effect: write
      questions:
      - How do I change the text of a comment I already posted?
      - Can I guard a comment edit with its version so I don't overwrite someone else's change?
      instructions:
      - text: Change comment {comment_id} on {resource_type} {resource_id} to {message}.
        slots:
          comment_id: path.comment_id
          resource_type: path.resource_type
          resource_id: path.resource_id
          message: requestBody.message
      - text: Edit comment {comment_id} on {resource_type} {resource_id} at version {version} to read {message}.
        slots:
          comment_id: path.comment_id
          resource_type: path.resource_type
          resource_id: path.resource_id
          version: query.version
          message: requestBody.message
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comments/{resource_type}/{resource_id}/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment
      effect: destructive
      questions:
      - How do I remove a comment from a resource?
      - Can I make sure I only delete a comment if nobody changed it since I read it?
      instructions:
      - text: Delete comment {comment_id} from {resource_type} {resource_id}.
        slots:
          comment_id: path.comment_id
          resource_type: path.resource_type
          resource_id: path.resource_id
      - text: Remove comment {comment_id} on {resource_type} {resource_id} only if it's at version {version}.
        slots:
          comment_id: path.comment_id
          resource_type: path.resource_type
          resource_id: path.resource_id
          version: query.version
      method: generated
      generated: '2026-09-26'