Elastic Stack (ELK Stack) Connector API

openapi: 3.2.0
info:
  title: Elasticsearch Request & Response Specification Connector API
  license:
    name: Apache 2.0
    url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
  version: ''
tags:
- name: connector
paths:
  /_connector/{connector_id}/_check_in:
    put:
      tags:
      - connector
      summary: Check in a connector
      description: Update the `last_seen` field in the connector and set it to the current timestamp.
      operationId: connector-check-in
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be checked in
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - result
              examples:
                ConnectorCheckInResponseExample1:
                  value: "{\n    \"result\": \"updated\"\n}"
      x-state: Experimental; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/{connector_id}:
    get:
      tags:
      - connector
      summary: Get a connector
      description: Get the details about a connector.
      operationId: connector-get
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: include_deleted
        description: A flag to indicate if the desired connector should be fetched, even if it was soft-deleted.
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connector._types.Connector'
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    put:
      tags:
      - connector
      summary: Create or update a connector
      operationId: connector-put
      parameters:
      - $ref: '#/components/parameters/connector.put-connector_id'
      requestBody:
        $ref: '#/components/requestBodies/connector.put'
      responses:
        '200':
          $ref: '#/components/responses/connector.put-200'
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    delete:
      tags:
      - connector
      summary: Delete a connector
      description: 'Removes a connector and associated sync jobs.

        This is a destructive action that is not recoverable.

        NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector.

        These need to be removed manually.'
      operationId: connector-delete
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be deleted
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: delete_sync_jobs
        description: A flag indicating if associated sync jobs should be also removed.
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      - in: query
        name: hard
        description: A flag indicating if the connector should be hard deleted.
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
              examples:
                ConnectorDeleteResponseExample1:
                  value: "{\n    \"acknowledged\": true\n}"
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector:
    get:
      tags:
      - connector
      summary: Get all connectors
      description: Get information about all connectors.
      operationId: connector-list
      parameters:
      - in: query
        name: from
        description: Starting offset
        deprecated: false
        schema:
          default: 0.0
          type: number
        style: form
      - in: query
        name: size
        description: Specifies a max number of results to get
        deprecated: false
        schema:
          default: 100.0
          type: number
        style: form
      - in: query
        name: index_name
        description: A comma-separated list of connector index names to fetch connector documents for
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Indices'
        style: form
      - in: query
        name: connector_name
        description: A comma-separated list of connector names to fetch connector documents for
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Names'
        style: form
      - in: query
        name: service_type
        description: A comma-separated list of connector service types to fetch connector documents for
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Names'
        style: form
      - in: query
        name: include_deleted
        description: A flag to indicate if the desired connector should be fetched, even if it was soft-deleted.
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      - in: query
        name: query
        description: A wildcard query string that filters connectors with matching name, description or index name
        deprecated: false
        schema:
          type: string
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/connector._types.Connector'
                required:
                - count
                - results
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    put:
      tags:
      - connector
      summary: Create or update a connector
      operationId: connector-put-1
      requestBody:
        $ref: '#/components/requestBodies/connector.put'
      responses:
        '200':
          $ref: '#/components/responses/connector.put-200'
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    post:
      tags:
      - connector
      summary: Create a connector
      description: 'Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure.

        Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud.

        Self-managed connectors (Connector clients) are self-managed on your infrastructure.'
      operationId: connector-post
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                index_name:
                  allOf:
                  - $ref: '#/components/schemas/_types.IndexName'
                is_native:
                  type: boolean
                language:
                  type: string
                name:
                  type: string
                service_type:
                  type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                  id:
                    allOf:
                    - $ref: '#/components/schemas/_types.Id'
                required:
                - result
                - id
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job/{connector_sync_job_id}/_cancel:
    put:
      tags:
      - connector
      summary: Cancel a connector sync job
      description: 'Cancel a connector sync job, which sets the status to cancelling and updates `cancellation_requested_at` to the current time.

        The connector service is then responsible for setting the status of connector sync jobs to cancelled.'
      operationId: connector-sync-job-cancel
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier of the connector sync job
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - result
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job/{connector_sync_job_id}/_check_in:
    put:
      tags:
      - connector
      summary: Check in a connector sync job
      description: 'Check in a connector sync job and set the `last_seen` field to the current time before updating it in the internal index.


        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure.

        This service runs automatically on Elastic Cloud for Elastic managed connectors.'
      operationId: connector-sync-job-check-in
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier of the connector sync job to be checked in.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      x-state: Experimental
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job/{connector_sync_job_id}/_claim:
    put:
      tags:
      - connector
      summary: Claim a connector sync job
      description: 'This action updates the job status to `in_progress` and sets the `last_seen` and `started_at` timestamps to the current time.

        Additionally, it can set the `sync_cursor` property for the sync job.


        This API is not intended for direct connector management by users.

        It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.


        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure.

        This service runs automatically on Elastic Cloud for Elastic managed connectors.'
      operationId: connector-sync-job-claim
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier of the connector sync job.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sync_cursor:
                  description: 'The cursor object from the last incremental sync job.

                    This should reference the `sync_cursor` field in the connector state for which the job runs.'
                  type: object
                worker_hostname:
                  description: The host name of the current system that will run the job.
                  type: string
              required:
              - worker_hostname
            examples:
              ConnectorSyncJobClaimExample1:
                description: An example body for a `PUT _connector/_sync_job/my-connector-sync-job-id/_claim` request.
                value: "{\n  \"worker_hostname\": \"some-machine\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      x-state: Experimental
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job/{connector_sync_job_id}:
    get:
      tags:
      - connector
      summary: Get a connector sync job
      operationId: connector-sync-job-get
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier of the connector sync job
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connector._types.ConnectorSyncJob'
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    delete:
      tags:
      - connector
      summary: Delete a connector sync job
      description: 'Remove a connector sync job and its associated data.

        This is a destructive action that is not recoverable.'
      operationId: connector-sync-job-delete
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier of the connector sync job to be deleted
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
              examples:
                SyncJobDeleteResponseExample1:
                  value: "{\n  \"acknowledged\": true\n}"
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job/{connector_sync_job_id}/_error:
    put:
      tags:
      - connector
      summary: Set a connector sync job error
      description: 'Set the `error` field for a connector sync job and set its `status` to `error`.


        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure.

        This service runs automatically on Elastic Cloud for Elastic managed connectors.'
      operationId: connector-sync-job-error
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier for the connector sync job.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                error:
                  description: The error for the connector sync job error field.
                  type: string
              required:
              - error
            examples:
              SyncJobErrorRequestExample1:
                value: "{\n    \"error\": \"some-error\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      x-state: Experimental
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job:
    get:
      tags:
      - connector
      summary: Get all connector sync jobs
      description: Get information about all stored connector sync jobs listed by their creation date in ascending order.
      operationId: connector-sync-job-list
      parameters:
      - in: query
        name: from
        description: Starting offset
        deprecated: false
        schema:
          default: 0.0
          type: number
        style: form
      - in: query
        name: size
        description: Specifies a max number of results to get
        deprecated: false
        schema:
          default: 100.0
          type: number
        style: form
      - in: query
        name: status
        description: A sync job status to fetch connector sync jobs for
        deprecated: false
        schema:
          $ref: '#/components/schemas/connector._types.SyncStatus'
        style: form
      - in: query
        name: connector_id
        description: A connector id to fetch connector sync jobs for
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: form
      - in: query
        name: job_type
        description: A comma-separated list of job types to fetch the sync jobs for
        deprecated: false
        schema:
          oneOf:
          - $ref: '#/components/schemas/connector._types.SyncJobType'
          - type: array
            items:
              $ref: '#/components/schemas/connector._types.SyncJobType'
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/connector._types.ConnectorSyncJob'
                required:
                - count
                - results
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    post:
      tags:
      - connector
      summary: Create a connector sync job
      description: Create a connector sync job document in the internal index and initialize its counters and timestamps with default values.
      operationId: connector-sync-job-post
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  description: The id of the associated connector
                  allOf:
                  - $ref: '#/components/schemas/_types.Id'
                job_type:
                  allOf:
                  - $ref: '#/components/schemas/connector._types.SyncJobType'
                trigger_method:
                  allOf:
                  - $ref: '#/components/schemas/connector._types.SyncJobTriggerMethod'
              required:
              - id
            examples:
              SyncJobPostRequestExample1:
                value: "{\n  \"id\": \"connector-id\",\n  \"job_type\": \"full\",\n  \"trigger_method\": \"on_demand\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    allOf:
                    - $ref: '#/components/schemas/_types.Id'
                required:
                - id
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/_sync_job/{connector_sync_job_id}/_stats:
    put:
      tags:
      - connector
      summary: Set the connector sync job stats
      description: 'Stats include: `deleted_document_count`, `indexed_document_count`, `indexed_document_volume`, and `total_document_count`.

        You can also update `last_seen`.

        This API is mainly used by the connector service for updating sync job information.


        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure.

        This service runs automatically on Elastic Cloud for Elastic managed connectors.'
      operationId: connector-sync-job-update-stats
      parameters:
      - in: path
        name: connector_sync_job_id
        description: The unique identifier of the connector sync job.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                deleted_document_count:
                  description: The number of documents the sync job deleted.
                  type: number
                indexed_document_count:
                  description: The number of documents the sync job indexed.
                  type: number
                indexed_document_volume:
                  description: The total size of the data (in MiB) the sync job indexed.
                  type: number
                last_seen:
                  description: The timestamp to use in the `last_seen` property for the connector sync job.
                  allOf:
                  - $ref: '#/components/schemas/_types.Duration'
                metadata:
                  description: The connector-specific metadata.
                  allOf:
                  - $ref: '#/components/schemas/_types.Metadata'
                total_document_count:
                  description: The total number of documents in the target index after the sync job finished.
                  type: number
              required:
              - deleted_document_count
              - indexed_document_count
              - indexed_document_volume
            examples:
              ConnectorSyncJobUpdateStatsExample1:
                description: An example body for a `PUT _connector/_sync_job/my-connector-sync-job/_stats` request.
                value: "{\n    \"deleted_document_count\": 10,\n    \"indexed_document_count\": 20,\n    \"indexed_document_volume\": 1000,\n    \"total_document_count\": 2000,\n    \"last_seen\": \"2023-01-02T10:00:00Z\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      x-state: Experimental
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/{connector_id}/_filtering/_activate:
    put:
      tags:
      - connector
      summary: Activate the connector draft filter
      description: Activates the valid draft filtering for a connector.
      operationId: connector-update-active-filtering
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be updated
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - result
      x-state: Experimental; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/{connector_id}/_api_key_id:
    put:
      tags:
      - connector
      summary: Update the connector API key ID
      description: 'Update the `api_key_id` and `api_key_secret_id` fields of a connector.

        You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored.

        The connector secret ID is required only for Elastic managed (native) connectors.

        Self-managed connectors (connector clients) do not use this field.'
      operationId: connector-update-api-key-id
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be updated
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                api_key_id:
                  type: string
                api_key_secret_id:
                  type: string
            examples:
              ConnectorUpdateApiKeyIDRequestExample1:
                value: "{\n    \"api_key_id\": \"my-api-key-id\",\n    \"api_key_secret_id\": \"my-connector-secret-id\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - result
              examples:
                ConnectorUpdateAPIKeyIDResponseExample1:
                  value: "{\n  \"result\": \"updated\"\n}"
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/{connector_id}/_configuration:
    put:
      tags:
      - connector
      summary: Update the connector configuration
      description: Update the configuration field in the connector document.
      operationId: connector-update-configuration
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be updated
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                configuration:
                  allOf:
                  - $ref: '#/components/schemas/connector._types.ConnectorConfiguration'
                values:
                  type: object
                  additionalProperties:
                    type: object
            examples:
              ConnectorUpdateConfigurationRequestExample1:
                value: "{\n    \"values\": {\n        \"tenant_id\": \"my-tenant-id\",\n        \"tenant_name\": \"my-sharepoint-site\",\n        \"client_id\": \"foo\",\n        \"secret_value\": \"bar\",\n        \"site_collections\": \"*\"\n    }\n}"
              ConnectorUpdateConfigurationRequestExample2:
                value: "{\n    \"values\": {\n        \"secret_value\": \"foo-bar\"\n    }\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - result
              examples:
                ConnectorUpdateConfigurationResponseExample1:
                  value: "{\n  \"result\": \"updated\"\n}"
      x-state: Beta; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/{connector_id}/_error:
    put:
      tags:
      - connector
      summary: Update the connector error field
      description: 'Set the error field for the connector.

        If the error provided in the request body is non-null, the connector’s status is updated to error.

        Otherwise, if the error is reset to null, the connector status is updated to connected.'
      operationId: connector-update-error
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be updated
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                error:
                  oneOf:
                  - type: string
                  - $ref: '#/components/schemas/_spec_utils.NullValue'
              required:
              - error
            examples:
              ConnectorUpdateErrorRequestExample1:
                value: "{\n    \"error\": \"Houston, we have a problem!\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - result
              examples:
                ConnectorUpdateErrorResponseExample1:
                  value: "{\n  \"result\": \"updated\"\n}"
      x-state: Experimental; Added in 8.12.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_connector/{connector_id}/_features:
    put:
      tags:
      - connector
      summary: Update the connector features
      description: 'Update the connector features in the connector document.

        This API can be used to control the following aspects of a connector:


        * document-level security

        * incremental syncs

        * advanced sync rules

        * basic sync rules


        Normally, the running connector service automatically manages these features.

        However, you can use this API to override the default behavior.


        To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure.

        This service runs automatically on Elastic Cloud for Elastic managed connectors.'
      operationId: connector-update-features
      parameters:
      - in: path
        name: connector_id
        description: The unique identifier of the connector to be updated.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                features:
                  allOf:
                  - $ref: '#/components/schemas/connector._types.ConnectorFeatures'
              required:
              - features
            examples:
              ConnectorUpdateFeaturesRequestExample1:
                value: "{\n  \"features\": {\n    \"document_level_security\": {\n      \"enabled\": true\n    },\n    \"incremental_sync\": {\n      \"enabled\": true\n    },\n    \"sync_rules\": {\n      \"advanced\": {\n        \"enabled\": false\n      },\n      \"basic\": {\n        \"enabled\": true\n      }\n    }\n  }\n}"
              ConnectorUpdateFeaturesRequestExample2:
                value: "{\n  \"features\": {\n    \"document_level_security\": {\n      \"enabled\": true\n    }\n  }\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                required:
                - res

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-connector-api-openapi.yml