openapi: 3.0.2
info:
  title: Ingestion API
  description: |
    The Ingestion API lets you connect third-party services and platforms with Algolia and schedule tasks to ingest your data.
    The Ingestion API powers the no-code [data connectors](https://dashboard.algolia.com/connectors).

    # Base URLs

    The base URLs for making requests to the Ingestion API are:

    - `https://data.us.algolia.com`
    - `https://data.eu.algolia.com`

    Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).

    **All requests must use HTTPS.**

    # Authentication

    To authenticate your API requests, add these headers:

    <dl>
    <dt><code>x-algolia-application-id</code></dt>
    <dd>Your Algolia application ID.</dd>
    <dt><code>x-algolia-api-key</code></dt>
    <dd>
    An API key with the necessary permissions to make the request.
    The required access control list (ACL) to make a request is listed in each endpoint's reference.
    </dd>
    </dl>

    You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account).

    # Request format

    Request bodies must be JSON objects.

    # Response status and errors

    Response bodies are JSON objects.
    Deleting a user token returns an empty response body with rate-limiting information as headers.

    Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
    Error responses have a `message` property with more information.

    The Insights API doesn't validate if the event parameters such as `indexName`, `objectIDs`, or `userToken`,
    correspond to anything in the Search API. It justs checks if they're formatted correctly.
    Check the [Events](https://dashboard.algolia.com/events/health) health section,
    whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking.

    # Version

    The current version of the Insights API is version 1, as indicated by the `/1/` in each endpoint's URL.

  version: 1.0.0
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
servers:
  - url: https://data.{region}.algolia.com
    variables:
      region:
        enum:
          - eu
          - us
        default: us
security:
  - appId: []
    apiKey: []
tags:
  - name: authentications
    x-displayName: Authentications
    description: Authentication resources describe how to connect to a source or destination.
  - name: destinations
    x-displayName: Destinations
    description: |
      Destinations are Algolia products or features where your data should be used, such as a search index or events.
      Algolia destinations require authentication with the `algolia` type.
      You can reference authentications by their ID when creating destinations.
  - name: observability
    x-displayName: Observability
    description: Check the status and details of your task runs. A run is one instance of a configured task.
  - name: sources
    x-displayName: Sources
    description: |
      Sources are third-party platforms or services from where you want to ingest your data.
      Sources may require authentication. To interact with such sources, you can reference an authentication resource by its ID.
  - name: tasks
    x-displayName: Tasks
    description: |
      Tasks contain information how your data should be read from a source and stored in a destination.
      Tasks have _triggers_ which determine when the task should run.
x-tagGroups:
  - name: Resources
    tags:
      - authentications
      - sources
      - destinations
      - tasks
      - observability
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  # authentications API.
  /1/authentications:
    $ref: 'paths/authentications/authentications.yml'
  /1/authentications/search:
    $ref: 'paths/authentications/searchAuthentications.yml'
  /1/authentications/{authenticationID}:
    $ref: 'paths/authentications/authenticationID.yml'

  # destinations API.
  /1/destinations:
    $ref: 'paths/destinations/destinations.yml'
  /1/destinations/search:
    $ref: 'paths/destinations/searchDestinations.yml'
  /1/destinations/{destinationID}:
    $ref: 'paths/destinations/destinationID.yml'

  # sources API.
  /1/sources:
    $ref: 'paths/sources/sources.yml'
  /1/sources/search:
    $ref: 'paths/sources/searchSources.yml'
  /1/sources/{sourceID}:
    $ref: 'paths/sources/sourceID.yml'
  /1/sources/{sourceID}/discover:
    $ref: 'paths/sources/discover.yml'

  # tasks API.
  /1/tasks:
    $ref: 'paths/tasks/tasks.yml'
  /1/tasks/search:
    $ref: 'paths/tasks/searchTasks.yml'
  /1/tasks/{taskID}:
    $ref: 'paths/tasks/taskID.yml'
  /1/tasks/{taskID}/run:
    $ref: 'paths/tasks/runTask.yml'
  /1/tasks/{taskID}/enable:
    $ref: 'paths/tasks/enableTask.yml'
  /1/tasks/{taskID}/disable:
    $ref: 'paths/tasks/disableTask.yml'

  # observability API.
  /1/runs:
    $ref: 'paths/runs/runs.yml'
  /1/runs/{runID}:
    $ref: 'paths/runs/runID.yml'
  /1/runs/{runID}/events:
    $ref: 'paths/runs/events/events.yml'
  /1/runs/{runID}/events/{eventID}:
    $ref: 'paths/runs/events/eventID.yml'