# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elasticsearch Request & Response Specification Connector API
  version: 1.0.0
extends: openapi/elk-stack-connector-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: 30
- target: $.paths['/_connector/{connector_id}/_check_in'].put
  update:
    x-apievangelist-phrasing:
      intent: Record a connector heartbeat
      effect: write
      questions:
      - How does a self-managed connector tell Elasticsearch it is still alive?
      - Which field gets bumped to the current time when a connector checks in?
      instructions:
      - text: Check in connector {connector_id} so its last_seen is now.
        slots:
          connector_id: path.connector_id
      - text: Send a heartbeat for connector {connector_id}.
        slots:
          connector_id: path.connector_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a connector's details
      effect: read
      questions:
      - What configuration, status and index does a particular connector have?
      - Can I still look up a connector that was soft-deleted?
      instructions:
      - text: Show me connector {connector_id}.
        slots:
          connector_id: path.connector_id
      - text: Get connector {connector_id} even if deleted, include_deleted {include_deleted}.
        slots:
          connector_id: path.connector_id
          include_deleted: query.include_deleted
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a connector with a chosen ID
      effect: write
      questions:
      - Can I create a connector under an ID I pick myself, or overwrite the one at that ID?
      - Which index and service type do I set when upserting a connector by its ID?
      instructions:
      - text: Create or replace connector {connector_id} writing to index {index_name}.
        slots:
          connector_id: path.connector_id
          index_name: requestBody.index_name
      - text: Upsert connector {connector_id} with service type {service_type} and name {name}.
        slots:
          connector_id: path.connector_id
          service_type: requestBody.service_type
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a connector
      effect: destructive
      questions:
      - Does deleting a connector also remove its data index and API keys?
      - Can I delete a connector together with all its sync jobs, or hard-delete it?
      instructions:
      - text: Delete connector {connector_id}.
        slots:
          connector_id: path.connector_id
      - text: Remove connector {connector_id} and its sync jobs, delete_sync_jobs {delete_sync_jobs}.
        slots:
          connector_id: path.connector_id
          delete_sync_jobs: query.delete_sync_jobs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector'].get
  update:
    x-apievangelist-phrasing:
      intent: List connectors
      effect: read
      questions:
      - What connectors are configured in my Elasticsearch cluster?
      - Can I filter the connector list by service type or target index name?
      instructions:
      - text: List all connectors of service type {service_type}.
        slots:
          service_type: query.service_type
      - text: Find connectors that write to index {index_name}.
        slots:
          index_name: query.index_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a connector via PUT without an ID
      effect: write
      questions:
      - Can I PUT a connector to the collection path and let Elasticsearch generate its ID?
      - What body fields does the ID-less PUT connector upsert accept?
      instructions:
      - text: PUT a new connector named {name} for index {index_name} without specifying an ID.
        slots:
          name: requestBody.name
          index_name: requestBody.index_name
      - text: Use the ID-less PUT endpoint to register a {service_type} connector.
        slots:
          service_type: requestBody.service_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a connector with a generated ID
      effect: write
      questions:
      - How do I add a new connector that syncs third-party content into an Elasticsearch index?
      - Can I make an Elastic managed native connector when I create it with POST?
      instructions:
      - text: Create a new connector for service type {service_type} syncing into {index_name}.
        slots:
          service_type: requestBody.service_type
          index_name: requestBody.index_name
      - text: POST a connector named {name} with is_native set to {is_native}.
        slots:
          name: requestBody.name
          is_native: requestBody.is_native
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}/_cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel a connector sync job
      effect: destructive
      questions:
      - How can I stop a connector sync that is currently running?
      - What status does a sync job move to after I request cancellation?
      instructions:
      - text: Cancel sync job {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      - text: Stop the running connector sync {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}/_check_in'].put
  update:
    x-apievangelist-phrasing:
      intent: Record a sync job heartbeat
      effect: write
      questions:
      - How does the connector service signal that a sync job is still progressing?
      - Which timestamp is updated when a sync job checks in?
      instructions:
      - text: Check in sync job {connector_sync_job_id} to update its last_seen.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      - text: Send a heartbeat for connector sync job {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}/_claim'].put
  update:
    x-apievangelist-phrasing:
      intent: Claim a sync job for a worker
      effect: write
      questions:
      - How does a connector worker take ownership of a pending sync job and mark it in progress?
      - Can I set a sync cursor when a worker claims a job?
      instructions:
      - text: Claim sync job {connector_sync_job_id} for worker host {worker_hostname}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
          worker_hostname: requestBody.worker_hostname
      - text: Mark job {connector_sync_job_id} in progress on {worker_hostname} with cursor {sync_cursor}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
          worker_hostname: requestBody.worker_hostname
          sync_cursor: requestBody.sync_cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a connector sync job
      effect: read
      questions:
      - What is the status and document count of one specific sync job?
      - Can I look up a single connector sync job by its ID?
      instructions:
      - text: Show sync job {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      - text: Get the details of connector sync run {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a connector sync job
      effect: destructive
      questions:
      - Can I permanently remove a sync job record and its data?
      - Is deleting a connector sync job reversible?
      instructions:
      - text: Delete sync job {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      - text: Permanently remove connector sync job record {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}/_error'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a sync job as failed
      effect: write
      questions:
      - How does the connector service report that a sync job failed with an error message?
      - What happens to a sync job's status when its error field is set?
      instructions:
      - text: Set sync job {connector_sync_job_id} to error with message {error}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
          error: requestBody.error
      - text: Fail connector sync job {connector_sync_job_id} because {error}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
          error: requestBody.error
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job'].get
  update:
    x-apievangelist-phrasing:
      intent: List connector sync jobs
      effect: read
      questions:
      - Which sync jobs have run for a given connector?
      - Can I filter sync jobs by status or job type, like only failed full syncs?
      instructions:
      - text: List sync jobs for connector {connector_id}.
        slots:
          connector_id: query.connector_id
      - text: Show all sync jobs with status {status} and type {job_type}.
        slots:
          status: query.status
          job_type: query.job_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new connector sync job
      effect: write
      questions:
      - How do I trigger a sync for a connector, full or incremental?
      - Can I choose the job type when creating a sync job?
      instructions:
      - text: Create a sync job for connector {id}.
        slots:
          id: requestBody.id
      - text: Queue a {job_type} sync for connector {id} triggered {trigger_method}.
        slots:
          job_type: requestBody.job_type
          id: requestBody.id
          trigger_method: requestBody.trigger_method
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/_sync_job/{connector_sync_job_id}/_stats'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a sync job's document counters
      effect: write
      questions:
      - How does the connector service report indexed and deleted document counts for a sync job?
      - Which stats fields are required when updating sync job progress?
      instructions:
      - text: 'Set stats on sync job {connector_sync_job_id}: indexed {indexed_document_count}, deleted {deleted_document_count}, volume {indexed_document_volume}.'
        slots:
          connector_sync_job_id: path.connector_sync_job_id
          indexed_document_count: requestBody.indexed_document_count
          deleted_document_count: requestBody.deleted_document_count
          indexed_document_volume: requestBody.indexed_document_volume
      - text: Record total document count {total_document_count} on job {connector_sync_job_id}.
        slots:
          connector_sync_job_id: path.connector_sync_job_id
          total_document_count: requestBody.total_document_count
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_filtering/_activate'].put
  update:
    x-apievangelist-phrasing:
      intent: Activate a connector's draft filtering
      effect: write
      questions:
      - How do I promote validated draft sync rules so a connector starts using them?
      - Can a connector's draft filter be made active once it passes validation?
      instructions:
      - text: Activate the draft filtering rules on connector {connector_id}.
        slots:
          connector_id: path.connector_id
      - text: Promote the validated draft filter to active for {connector_id}.
        slots:
          connector_id: path.connector_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_api_key_id'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the API key a connector uses
      effect: write
      questions:
      - Where do I tell a connector which API key and stored secret to authenticate with?
      - Can I update a connector's API key secret ID separately?
      instructions:
      - text: Set connector {connector_id} to use API key ID {api_key_id}.
        slots:
          connector_id: path.connector_id
          api_key_id: requestBody.api_key_id
      - text: Point connector {connector_id} at connector secret {api_key_secret_id}.
        slots:
          connector_id: path.connector_id
          api_key_secret_id: requestBody.api_key_secret_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_configuration'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a connector's configuration values
      effect: write
      questions:
      - How do I change the settings a connector uses to reach its data source, like host or credentials?
      - Can I update only configuration values without redefining the whole schema?
      instructions:
      - text: Update connector {connector_id} configuration values to {values}.
        slots:
          connector_id: path.connector_id
          values: requestBody.values
      - text: Replace the configuration schema of {connector_id} with {configuration}.
        slots:
          connector_id: path.connector_id
          configuration: requestBody.configuration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_error'].put
  update:
    x-apievangelist-phrasing:
      intent: Set or clear a connector's error
      effect: write
      questions:
      - How can I flag a connector as errored, or reset it back to connected?
      - What status does a connector get when its error is cleared to null?
      instructions:
      - text: Set error {error} on connector {connector_id}.
        slots:
          connector_id: path.connector_id
          error: requestBody.error
      - text: Record connector-level error {error} for {connector_id}.
        slots:
          connector_id: path.connector_id
          error: requestBody.error
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_features'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a connector's enabled features
      effect: write
      questions:
      - Can I turn on document-level security or incremental syncs for a connector?
      - Which connector features, such as advanced sync rules, can be toggled?
      instructions:
      - text: Set the features of connector {connector_id} to {features}.
        slots:
          connector_id: path.connector_id
          features: requestBody.features
      - text: Enable incremental syncs on {connector_id} via features {features}.
        slots:
          connector_id: path.connector_id
          features: requestBody.features
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_filtering'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a connector's draft sync rules
      effect: write
      questions:
      - How do I change which documents a connector syncs using basic or advanced rules?
      - Can I add an advanced sync rule snippet to a connector's draft filtering?
      instructions:
      - text: Set draft sync rules {rules} on connector {connector_id}.
        slots:
          connector_id: path.connector_id
          rules: requestBody.rules
      - text: Add advanced snippet {advanced_snippet} to the draft filtering of {connector_id}.
        slots:
          connector_id: path.connector_id
          advanced_snippet: requestBody.advanced_snippet
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_filtering/_validation'].put
  update:
    x-apievangelist-phrasing:
      intent: Record draft filtering validation results
      effect: write
      questions:
      - How does the connector service mark draft sync rules as valid or invalid?
      - Where do filtering validation errors for a connector get stored?
      instructions:
      - text: Set filtering validation {validation} on connector {connector_id}.
        slots:
          connector_id: path.connector_id
          validation: requestBody.validation
      - text: Mark the draft filter of {connector_id} as validated with {validation}.
        slots:
          connector_id: path.connector_id
          validation: requestBody.validation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_index_name'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a connector's target index
      effect: write
      questions:
      - Can I change which index a connector writes its ingested content to?
      - How is the destination index of a connector updated?
      instructions:
      - text: Point connector {connector_id} at index {index_name}.
        slots:
          connector_id: path.connector_id
          index_name: requestBody.index_name
      - text: Change where {connector_id} stores synced data to {index_name}.
        slots:
          connector_id: path.connector_id
          index_name: requestBody.index_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_name'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a connector
      effect: write
      questions:
      - How do I rename a connector or edit its description?
      - Can I change only a connector's display name?
      instructions:
      - text: Rename connector {connector_id} to {name}.
        slots:
          connector_id: path.connector_id
          name: requestBody.name
      - text: Set the description of connector {connector_id} to {description}.
        slots:
          connector_id: path.connector_id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_native'].put
  update:
    x-apievangelist-phrasing:
      intent: Switch a connector between native and self-managed
      effect: write
      questions:
      - Can I convert a connector between Elastic managed and self-managed?
      - What does the is_native flag on a connector control?
      instructions:
      - text: Set is_native to {is_native} on connector {connector_id}.
        slots:
          connector_id: path.connector_id
          is_native: requestBody.is_native
      - text: Make connector {connector_id} self-managed by setting native to {is_native}.
        slots:
          connector_id: path.connector_id
          is_native: requestBody.is_native
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_pipeline'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a connector's ingest pipeline
      effect: write
      questions:
      - Which ingest pipeline does a connector send documents through, and can I change it?
      - Can I override the default pipeline settings a connector was created with?
      instructions:
      - text: Set the ingest pipeline of connector {connector_id} to {pipeline}.
        slots:
          connector_id: path.connector_id
          pipeline: requestBody.pipeline
      - text: Update pipeline settings for {connector_id} to {pipeline}.
        slots:
          connector_id: path.connector_id
          pipeline: requestBody.pipeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_scheduling'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a connector's sync schedule
      effect: write
      questions:
      - How do I make a connector run full syncs on a cron schedule?
      - Can I schedule incremental and access control syncs separately?
      instructions:
      - text: Set the sync schedule of connector {connector_id} to {scheduling}.
        slots:
          connector_id: path.connector_id
          scheduling: requestBody.scheduling
      - text: Update scheduling for {connector_id} with {scheduling}.
        slots:
          connector_id: path.connector_id
          scheduling: requestBody.scheduling
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_service_type'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a connector's service type
      effect: write
      questions:
      - Can I change what kind of data source a connector is for after creating it?
      - Where is a connector's service type updated?
      instructions:
      - text: Change service type of connector {connector_id} to {service_type}.
        slots:
          connector_id: path.connector_id
          service_type: requestBody.service_type
      - text: Make {connector_id} a {service_type} connector.
        slots:
          connector_id: path.connector_id
          service_type: requestBody.service_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_connector/{connector_id}/_status'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a connector's status
      effect: write
      questions:
      - How do I manually set a connector's status, such as configured or connected?
      - Can the status field of a connector be updated directly?
      instructions:
      - text: Set connector {connector_id} status to {status}.
        slots:
          connector_id: path.connector_id
          status: requestBody.status
      - text: Mark {connector_id} as {status}.
        slots:
          connector_id: path.connector_id
          status: requestBody.status
      method: generated
      generated: '2026-09-26'