API Evangelist conversational phrasing for Elk Stack Document API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elk Stack Document API
  version: 1.0.0
extends: openapi/elk-stack-document-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['/_bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Run bulk document actions via PUT on any index
      effect: write
      questions:
      - Can I send a PUT to the cluster-wide bulk endpoint with actions naming their own indices?
      - Which query options let a PUT bulk request fail when the target is not an alias?
      instructions:
      - text: Send a PUT bulk request with mixed index and delete actions, running them through pipeline {pipeline}.
        slots:
          pipeline: query.pipeline
      - text: Using PUT on the root bulk endpoint, apply my batch with refresh set to {refresh}.
        slots:
          refresh: query.refresh
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk index, update or delete documents
      effect: write
      questions:
      - How do I index thousands of documents in one request instead of one call each?
      - Can a single bulk POST mix create, update and delete actions across several indices?
      - What happens to throughput when I batch writes with the bulk API?
      instructions:
      - text: POST this NDJSON batch of create, update and delete actions to the bulk endpoint.
      - text: Bulk-load my documents with routing {routing} and wait for {wait_for_active_shards} active shards.
        slots:
          routing: query.routing
          wait_for_active_shards: query.wait_for_active_shards
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Run bulk document actions via PUT on one index
      effect: write
      questions:
      - Can I PUT a bulk batch scoped to one index so the actions don't repeat the index name?
      - Does a per-index PUT bulk request let me require the target to be a data stream?
      instructions:
      - text: PUT a bulk batch of actions into index {index}.
        slots:
          index: path.index
      - text: Using PUT, bulk write to {index} with require_data_stream {require_data_stream}.
        slots:
          index: path.index
          require_data_stream: query.require_data_stream
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk write documents into a single index
      effect: write
      questions:
      - How do I bulk load documents into one specific index without naming it on every line?
      - Can I see which ingest pipelines ran for each document in an index-scoped bulk load?
      instructions:
      - text: Bulk index my documents into {index} and list the executed pipelines.
        slots:
          index: path.index
      - text: POST a bulk batch to index {index} through ingest pipeline {pipeline}.
        slots:
          index: path.index
          pipeline: query.pipeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_create/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a document only if its ID is new (PUT)
      effect: write
      questions:
      - How do I add a document with a specific ID and fail if that ID already exists?
      - Can I create a new document with PUT on the _create endpoint and have it refresh immediately?
      instructions:
      - text: Create document {id} in {index} with PUT, failing if it already exists.
        slots:
          id: path.id
          index: path.index
      - text: PUT a brand-new document {id} into {index} and refresh with {refresh}.
        slots:
          id: path.id
          index: path.index
          refresh: query.refresh
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_create/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a document only if its ID is new (POST)
      effect: write
      questions:
      - Can I POST to the _create endpoint so a duplicate document ID is rejected rather than overwritten?
      - Which pipeline option applies when I POST a create-only document into a data stream?
      instructions:
      - text: POST to _create to add document {id} to {index} only if the ID is unused.
        slots:
          id: path.id
          index: path.index
      - text: Using POST on _create, insert document {id} in {index} via pipeline {pipeline}.
        slots:
          id: path.id
          index: path.index
          pipeline: query.pipeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_doc/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document by its ID
      effect: read
      questions:
      - How do I fetch a single document and its source when I know the index and ID?
      - Is reading one document by ID realtime, or does it wait for the index refresh?
      - Can I pull only certain stored fields of a document by ID?
      instructions:
      - text: Get document {id} from index {index}.
        slots:
          id: path.id
          index: path.index
      - text: Fetch document {id} in {index}, returning only source fields {_source_includes}.
        slots:
          id: path.id
          index: path.index
          _source_includes: query._source_includes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_doc/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Index or replace a document with PUT
      effect: write
      questions:
      - How do I save a JSON document under my own ID, overwriting it if it exists?
      - Can I make a PUT document write conditional on its sequence number and primary term?
      instructions:
      - text: PUT this JSON as document {id} in {index}, replacing any existing version.
        slots:
          id: path.id
          index: path.index
      - text: Overwrite document {id} in {index} only if its seq_no is {if_seq_no}.
        slots:
          id: path.id
          index: path.index
          if_seq_no: query.if_seq_no
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_doc/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Index or replace a document with POST and an ID
      effect: write
      questions:
      - Can I POST a document to _doc with an explicit ID to add or overwrite it?
      - Which op_type should I pass to a POST _doc request so it only creates?
      instructions:
      - text: POST my JSON to _doc as document {id} in index {index}.
        slots:
          id: path.id
          index: path.index
      - text: Using POST with ID {id}, write to {index} with op_type {op_type}.
        slots:
          id: path.id
          index: path.index
          op_type: query.op_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_doc/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document by ID
      effect: destructive
      questions:
      - How do I remove a single document from an index when I know its ID?
      - Why can't I delete a document directly from a data stream by ID?
      instructions:
      - text: Delete document {id} from index {index}.
        slots:
          id: path.id
          index: path.index
      - text: Remove document {id} in {index} only if its primary term is {if_primary_term}.
        slots:
          id: path.id
          index: path.index
          if_primary_term: query.if_primary_term
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_doc/{id}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check whether a document exists
      effect: read
      questions:
      - Is there a quick way to tell if a document ID exists without downloading it?
      - What status do I get back when a document I'm checking for is missing?
      instructions:
      - text: Check whether document {id} exists in {index}.
        slots:
          id: path.id
          index: path.index
      - text: Confirm document {id} is present in {index} using routing {routing}.
        slots:
          id: path.id
          index: path.index
          routing: query.routing
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_delete_by_query'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete all documents matching a query
      effect: destructive
      questions:
      - How do I delete every document that matches a search, not just one ID?
      - Can I cap how many matching documents a delete-by-query removes?
      - What happens on version conflicts while deleting documents by query?
      instructions:
      - text: Delete all documents in {index} matching query {query}.
        slots:
          index: path.index
          query: requestBody.query
      - text: Delete up to {max_docs} matching documents from {index}, proceeding on conflicts.
        slots:
          index: path.index
          max_docs: requestBody.max_docs
      - text: Run a delete-by-query on {index} for Lucene query {q} in the background.
        slots:
          index: path.index
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_delete_by_query/{task_id}/_rethrottle'].post
  update:
    x-apievangelist-phrasing:
      intent: Change the speed of a running delete by query
      effect: write
      questions:
      - Can I slow down a delete-by-query that is hammering my cluster?
      - Does speeding up a running delete by query take effect immediately?
      instructions:
      - text: Rethrottle delete-by-query task {task_id} to {requests_per_second} requests per second.
        slots:
          task_id: path.task_id
          requests_per_second: query.requests_per_second
      - text: Unthrottle the delete by query task {task_id} by setting its rate to {requests_per_second}.
        slots:
          task_id: path.task_id
          requests_per_second: query.requests_per_second
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_source/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get only a document's source
      effect: read
      questions:
      - How do I get just the original JSON body of a document without the metadata wrapper?
      - Can I filter which source fields come back when retrieving only a document's _source?
      instructions:
      - text: Return just the _source of document {id} in {index}.
        slots:
          id: path.id
          index: path.index
      - text: Get the raw source of {id} from {index}, excluding fields {_source_excludes}.
        slots:
          id: path.id
          index: path.index
          _source_excludes: query._source_excludes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_source/{id}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check whether a document's source is stored
      effect: read
      questions:
      - How can I tell if a document's _source is available, since it may be disabled in the mapping?
      - Is there a HEAD check for the stored source rather than the document itself?
      instructions:
      - text: Check whether the _source of document {id} in {index} is available.
        slots:
          id: path.id
          index: path.index
      - text: Verify a stored source exists for {id} in {index} at version {version}.
        slots:
          id: path.id
          index: path.index
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_doc'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document with an auto-generated ID
      effect: write
      questions:
      - How do I add a document and let the cluster generate its ID for me?
      - Can I append a log event to a data stream without choosing an ID?
      instructions:
      - text: Add this JSON document to {index} with an auto-generated ID.
        slots:
          index: path.index
      - text: Append a new event to data stream {index} through pipeline {pipeline}, letting it assign the ID.
        slots:
          index: path.index
          pipeline: query.pipeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_reindex'].post
  update:
    x-apievangelist-phrasing:
      intent: Copy documents from one index to another
      effect: write
      questions:
      - How do I copy all documents from an old index into a new one?
      - Can I reindex only a subset of documents or transform them with a script on the way?
      - What's the way to limit how fast a reindex runs so it doesn't overload the cluster?
      instructions:
      - text: Reindex documents from {source} into {dest}.
        slots:
          source: requestBody.source
          dest: requestBody.dest
      - text: Copy at most {max_docs} documents from {source} to {dest}.
        slots:
          max_docs: requestBody.max_docs
          source: requestBody.source
          dest: requestBody.dest
      - text: Reindex {source} into {dest} applying script {script}.
        slots:
          source: requestBody.source
          dest: requestBody.dest
          script: requestBody.script
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_mget'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch many documents by ID across indices
      effect: read
      questions:
      - How do I retrieve a batch of documents from different indices in one GET?
      - Can a multi-get pull documents by index and ID pairs with no index in the URL?
      instructions:
      - text: Multi-get the documents listed in {docs}, each with its own index and ID.
        slots:
          docs: requestBody.docs
      - text: With a GET multi-get across indices, fetch {docs} returning only stored fields {stored_fields}.
        slots:
          docs: requestBody.docs
          stored_fields: query.stored_fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_mget'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch many documents by ID across indices (POST)
      effect: read
      questions:
      - Can I POST a multi-get body naming documents from several indices at once?
      - Is there a POST form of multi-get for clients that can't send a GET body?
      instructions:
      - text: POST a multi-get for document specs {docs} spread over several indices.
        slots:
          docs: requestBody.docs
      - text: Using POST multi-get with no index in the path, retrieve {docs} realtime {realtime}.
        slots:
          docs: requestBody.docs
          realtime: query.realtime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_mget'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch many documents by ID from one index
      effect: read
      questions:
      - How do I get several documents from one index by just listing their IDs?
      - Can I multi-get from a single index and filter the source fields returned?
      instructions:
      - text: Get documents with IDs {ids} from index {index}.
        slots:
          ids: requestBody.ids
          index: path.index
      - text: From {index}, GET multiple documents {ids} including only fields {_source_includes}.
        slots:
          index: path.index
          ids: requestBody.ids
          _source_includes: query._source_includes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_mget'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch many documents from one index (POST)
      effect: read
      questions:
      - Can I POST a list of IDs to one index's multi-get endpoint?
      - Is there a POST version of index-scoped multi-get that honors routing?
      instructions:
      - text: POST IDs {ids} to the multi-get endpoint of {index}.
        slots:
          ids: requestBody.ids
          index: path.index
      - text: Using POST, multi-get {ids} in {index} with routing {routing}.
        slots:
          ids: requestBody.ids
          index: path.index
          routing: query.routing
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_mtermvectors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for many documents
      effect: read
      questions:
      - How do I get term statistics for several documents across indices in one GET request?
      - Can I request term vectors for artificial documents I provide rather than stored ones?
      instructions:
      - text: Get term vectors for documents {docs} across my indices.
        slots:
          docs: requestBody.docs
      - text: Fetch multi term vectors for {docs} with term statistics {term_statistics}.
        slots:
          docs: requestBody.docs
          term_statistics: query.term_statistics
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_mtermvectors'].post
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for many documents (POST)
      effect: read
      questions:
      - Can I POST a batch of document references to get their term vectors together?
      - Which positions and offsets can I include when posting a multi term vectors request?
      instructions:
      - text: POST a multi term vectors request for documents {docs}.
        slots:
          docs: requestBody.docs
      - text: Using POST, get term vectors for {docs} restricted to fields {fields}.
        slots:
          docs: requestBody.docs
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_mtermvectors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for many documents in one index
      effect: read
      questions:
      - How do I get term vectors for a list of document IDs within a single index?
      - Can I skip field statistics when pulling term vectors for many docs in one index?
      instructions:
      - text: Get term vectors for IDs {ids} in index {index}.
        slots:
          ids: query.ids
          index: path.index
      - text: Fetch multi term vectors from {index} for {ids} with field statistics {field_statistics}.
        slots:
          index: path.index
          ids: query.ids
          field_statistics: query.field_statistics
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_mtermvectors'].post
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for many docs in an index (POST)
      effect: read
      questions:
      - Can I POST document specs to one index's multi term vectors endpoint?
      - Is there a POST form for index-scoped multi term vectors with payloads included?
      instructions:
      - text: POST a multi term vectors request for {docs} to index {index}.
        slots:
          docs: requestBody.docs
          index: path.index
      - text: Using POST on {index}, get term vectors for {docs} including payloads {payloads}.
        slots:
          index: path.index
          docs: requestBody.docs
          payloads: query.payloads
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_reindex/{task_id}/_rethrottle'].post
  update:
    x-apievangelist-phrasing:
      intent: Change the speed of a running reindex
      effect: write
      questions:
      - Can I throttle a reindex that's already running?
      - How do I remove the rate limit from a reindex in progress?
      instructions:
      - text: Rethrottle reindex task {task_id} to {requests_per_second} documents per second.
        slots:
          task_id: path.task_id
          requests_per_second: query.requests_per_second
      - text: Unthrottle reindex {task_id} completely by setting requests per second to {requests_per_second}.
        slots:
          task_id: path.task_id
          requests_per_second: query.requests_per_second
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_termvectors/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for one stored document
      effect: read
      questions:
      - How do I see the terms, frequencies and positions for the fields of a single document?
      - Can I get term statistics for one stored document using a different analyzer per field?
      instructions:
      - text: Get term vectors for document {id} in {index}.
        slots:
          id: path.id
          index: path.index
      - text: Show term vectors of {id} in {index} for fields {fields} with offsets.
        slots:
          id: path.id
          index: path.index
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_termvectors/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for one stored document (POST)
      effect: read
      questions:
      - Can I POST a filter body to trim the term vectors returned for a single document?
      - Is there a POST variant of per-document term vectors that accepts per-field analyzers?
      instructions:
      - text: POST a term vectors request for document {id} in {index}.
        slots:
          id: path.id
          index: path.index
      - text: Using POST, get term vectors of {id} in {index} filtered by {filter}.
        slots:
          id: path.id
          index: path.index
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_termvectors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for an artificial document
      effect: read
      questions:
      - How do I analyze term vectors for text I supply that isn't stored in the index?
      - Can I get term statistics for an ad-hoc document against an index's mappings?
      instructions:
      - text: Compute term vectors in {index} for text I supply as {doc}, not a stored document.
        slots:
          index: path.index
          doc: requestBody.doc
      - text: Analyze supplied doc {doc} against {index} with per-field analyzer {per_field_analyzer}.
        slots:
          doc: requestBody.doc
          index: path.index
          per_field_analyzer: requestBody.per_field_analyzer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_termvectors'].post
  update:
    x-apievangelist-phrasing:
      intent: Get term vectors for an artificial doc (POST)
      effect: read
      questions:
      - Can I POST an inline document to an index to get its term vectors without saving it?
      - Is there a POST route for term vectors of supplied text with no document ID?
      instructions:
      - text: POST inline document {doc} to {index} and return its term vectors.
        slots:
          doc: requestBody.doc
          index: path.index
      - text: Using POST with no ID, compute term vectors of {doc} in {index} with positions {positions}.
        slots:
          doc: requestBody.doc
          index: path.index
          positions: query.positions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_update/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Partially update a document
      effect: write
      questions:
      - How do I change a few fields of a document without resending the whole thing?
      - Can I update a document with a script, or insert it if it doesn't exist yet?
      - How many times will a document update retry when it hits a version conflict?
      instructions:
      - text: Update document {id} in {index} with partial fields {doc}.
        slots:
          id: path.id
          index: path.index
          doc: requestBody.doc
      - text: Run script {script} on document {id} in {index}.
        slots:
          script: requestBody.script
          id: path.id
          index: path.index
      - text: 'Upsert document {id} in {index}: apply {doc}, or insert {upsert} if missing.'
        slots:
          id: path.id
          index: path.index
          doc: requestBody.doc
          upsert: requestBody.upsert
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{index}/_update_by_query'].post
  update:
    x-apievangelist-phrasing:
      intent: Update all documents matching a query
      effect: write
      questions:
      - How do I apply a change to every document that matches a query?
      - Can I re-run an ingest pipeline over existing documents in place after a mapping change?
      - What happens if no query is given to update by query?
      instructions:
      - text: Update every document in {index} matching {query} with script {script}.
        slots:
          index: path.index
          query: requestBody.query
          script: requestBody.script
      - text: Reprocess all documents in {index} in place through pipeline {pipeline}.
        slots:
          index: path.index
          pipeline: query.pipeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_update_by_query/{task_id}/_rethrottle'].post
  update:
    x-apievangelist-phrasing:
      intent: Change the speed of a running update by query
      effect: write
      questions:
      - Can I speed up or slow down an update-by-query that's in progress?
      - Does lowering the rate of a running update by query apply right away?
      instructions:
      - text: Rethrottle update-by-query task {task_id} to {requests_per_second} per second.
        slots:
          task_id: path.task_id
          requests_per_second: query.requests_per_second
      - text: Slow the update by query job {task_id} down to {requests_per_second} requests per second.
        slots:
          task_id: path.task_id
          requests_per_second: query.requests_per_second
      method: generated
      generated: '2026-09-26'