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

    ## Base URLs

    Base URLs for the Ingestion API:

    - `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

    Add these headers to authenticate requests:

    - `x-algolia-application-id`. Your Algolia application ID.
    - `x-algolia-api-key`. 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.

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

    ## Request format

    Request bodies must be JSON objects.

    ## Response status and errors

    Response bodies are JSON objects.

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

    ## Version

    The current version of the Ingestion API is version 1, 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:
        description: The region where your Algolia application is hosted.
        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.
  - name: transformations
    x-displayName: Transformations
    description: |
      Transformations let you transform a record before it gets indexed in Algolia.
x-tagGroups:
  - name: Resources
    tags:
      - authentications
      - destinations
      - observability
      - sources
      - tasks
      - transformations
x-timeouts:
  browser:
    connect: 25000
    read: 25000
    write: 25000
  server:
    connect: 25000
    read: 25000
    write: 25000
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  /1/push/{indexName}:
    $ref: 'paths/push.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/validate:
    $ref: 'paths/sources/validate.yml'
  /1/sources/search:
    $ref: 'paths/sources/searchSources.yml'
  /1/sources/{sourceID}:
    $ref: 'paths/sources/sourceID.yml'
  /1/sources/{sourceID}/validate:
    $ref: 'paths/sources/validateID.yml'
  /1/sources/{sourceID}/discover:
    $ref: 'paths/sources/discover.yml'
  /1/sources/{sourceID}/run:
    $ref: 'paths/sources/runSource.yml'

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

  # transformations API.
  /1/transformations:
    $ref: 'paths/transformations/transformations.yml'
  /1/transformations/try:
    $ref: 'paths/transformations/transformationsTry.yml'
  /1/transformations/search:
    $ref: 'paths/transformations/transformationsSearch.yml'
  /1/transformations/{transformationID}:
    $ref: 'paths/transformations/transformationID.yml'
  /1/transformations/{transformationID}/try:
    $ref: 'paths/transformations/transformationTryID.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'

  # ###############
  # ### Helpers ###
  # ###############
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'

  /chunkedPush:
    $ref: 'helpers/chunkedPush.yml#/method'