API reference / Ingestion API

Jun. 08, 2023

Ingestion API

API powering the Data Ingestion connectors of Algolia.

Base URLs

The Ingestion API has the following base URLs:

Use the server that matches your analytics region.

Authentication

To authenticate your API requests, add these headers:

X-Algolia-Application-Id: the ID of your Algolia application
X-Algolia-API-Key: an API key

You can find your application ID and manage your API keys in the Algolia dashboard.

Rate limiting

Requests to the Ingestion API are rate-limited:

Observability endpoints: up to 200 requests every 30 seconds per IP address
All other endpoints: up to 200 requests per minute per IP address

Authentications

An authentication describe the way we connect to Algolia, or any supported connector.

GET	`/1/authentications`	Get a list of authentications
POST	`/1/authentications`	Create a authentication
POST	`/1/authentications/search`	Search among authentications
GET	`/1/authentications/{authenticationID}`	Get a authentication
PATCH	`/1/authentications/{authenticationID}`	Update a authentication
DELETE	`/1/authentications/{authenticationID}`	Delete a authentication

Get a list of authentications

GET /1/authentications

Get a list of authentications for the given query parameters, with pagination details.

Query parameter

`itemsPerPage`	type: integer The number of items per page to return.
`page`	type: integer The page number to fetch, starting at 1.
`type`	type: array items: string One of: `googleServiceAccount`, `basic`, `apiKey`, `oauth`, `algolia` The type of the authentications to retrieve. Example:`type=basic,oauth`
`platform`	type: array items: platformWithNone One of: `bigcommerce`, `commercetools` , `none` The platform of the authentications to retrieve. Example:`platform=commercetools,none`
`sort`	type: string The key by which the list should be sorted.
`order`	type: string The order of the returned list.

Responses

200

Response body schema: application/json

authentications

type: array

items: object

required

`authenticationID`	type: string required The authentication UUID. Example:`6c02aeb1-775e-418e-870b-1faccd4b2c0f`
`type`	type: string required Type of the Authentication, defines what kind of object is stored in the input. One of: `googleServiceAccount`, `basic`, `apiKey`, `oauth`, `algolia`
`name`	type: string required An human readable name describing the object.
`platform`	type: string Describe which platform the Authentication is used for. One of: `bigcommerce`, `commercetools`
`createdAt`	type: string required Date of creation (RFC3339 format).
`updatedAt`	type: string Date of last update (RFC3339 format).

pagination

type: object

required

`nbPages`	type: integer required
`page`	type: integer required
`nbItems`	type: integer required
`itemsPerPage`	type: integer required

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Create a authentication

POST /1/authentications

Create a authentication.

Request body

Accepts: application/json

type

type: string

required

One of: googleServiceAccount, basic, apiKey, oauth, algolia

name

type: string

required

platform

type: string

One of: bigcommerce, commercetools

input

type: AuthInput

required

One of:

AuthGoogleServiceAccount

clientEmail

type: string

required

Email address of the Service Account.

Example:service-account-name@project-id.iam.gserviceaccount.com

privateKey

type: string

required

Private key of the Service Account.

AuthBasic

`username`	type: string required
`password`	type: string required

AuthAPIKey

key

type: string

required

AuthOAuth

`url`	type: string required The OAuth endpoint URL.
`client_id`	type: string required The clientID.
`client_secret`	type: string required The secret.

AuthAlgolia

`appID`	type: string required Algolia Application ID.
`apiKey`	type: string required Algolia API Key, with the correct rights to push to an index and change settings.

Responses

200

Response body schema: application/json

authenticationID

type: string

required

The authentication UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

name

type: string

required

An human readable name describing the object.

createdAt

type: string

required

Date of creation (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Search among authentications

POST /1/authentications/search

Search among authentications with a defined set of parameters.

Request body

Accepts: application/json

authenticationIDs

type: array

items: string

required

Responses

200

Response body schema: application/json

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get a authentication

GET /1/authentications/{authenticationID}

Get the authentication of the given authenticationID.

Path parameter

authenticationID

type: string

required

The authentication UUID.

Example:authenticationID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

authenticationID

type: string

required

The authentication UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

type

type: string

required

Type of the Authentication, defines what kind of object is stored in the input.

One of: googleServiceAccount, basic, apiKey, oauth, algolia

name

type: string

required

An human readable name describing the object.

platform

type: string

Describe which platform the Authentication is used for.

One of: bigcommerce, commercetools

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

input

type: AuthInput

required

One of:

AuthGoogleServiceAccount

clientEmail

type: string

required

Email address of the Service Account.

Example:service-account-name@project-id.iam.gserviceaccount.com

privateKey

type: string

required

Private key of the Service Account.

AuthBasic

`username`	type: string required
`password`	type: string required

AuthAPIKey

key

type: string

required

AuthOAuth

`url`	type: string required The OAuth endpoint URL.
`client_id`	type: string required The clientID.
`client_secret`	type: string required The secret.

AuthAlgolia

`appID`	type: string required Algolia Application ID.
`apiKey`	type: string required Algolia API Key, with the correct rights to push to an index and change settings.

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Update a authentication

PATCH /1/authentications/{authenticationID}

Update the authentication of the given authenticationID.

Path parameter

authenticationID

type: string

required

The authentication UUID.

Example:authenticationID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Request body

Accepts: application/json

type

type: string

One of: googleServiceAccount, basic, apiKey, oauth, algolia

name

type: string

platform

type: string

One of: bigcommerce, commercetools

input

type: AuthInput

One of:

AuthGoogleServiceAccount

clientEmail

type: string

required

Email address of the Service Account.

Example:service-account-name@project-id.iam.gserviceaccount.com

privateKey

type: string

required

Private key of the Service Account.

AuthBasic

`username`	type: string required
`password`	type: string required

AuthAPIKey

key

type: string

required

AuthOAuth

`url`	type: string required The OAuth endpoint URL.
`client_id`	type: string required The clientID.
`client_secret`	type: string required The secret.

AuthAlgolia

`appID`	type: string required Algolia Application ID.
`apiKey`	type: string required Algolia API Key, with the correct rights to push to an index and change settings.

Responses

200

Response body schema: application/json

authenticationID

type: string

required

The authentication UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

name

type: string

required

An human readable name describing the object.

updatedAt

type: string

required

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Delete a authentication

DELETE /1/authentications/{authenticationID}

Soft delete the authentication of the given authenticationID.

Path parameter

authenticationID

type: string

required

The authentication UUID.

Example:authenticationID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

deletedAt

type: string

required

Date of deletion (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Destinations

A destination refers to an Algolia product (Search, Insight, Recommend, …).

GET	`/1/destinations`	Get a list of destinations
POST	`/1/destinations`	Create a destination
POST	`/1/destinations/search`	Search among destinations
GET	`/1/destinations/{destinationID}`	Get a destination
PATCH	`/1/destinations/{destinationID}`	Update a destination
DELETE	`/1/destinations/{destinationID}`	Delete a destination

Get a list of destinations

GET /1/destinations

Get a list of destinations for the given query parameters, with pagination details.

Query parameter

`itemsPerPage`	type: integer The number of items per page to return.
`page`	type: integer The page number to fetch, starting at 1.
`type`	type: array items: string One of: `search`, `insights`, `flow`, `predict` The type of the destinations to retrive. Example:`type=search,predict`
`authenticationID`	type: array items: string The authenticationIDs of the destinations to retrive.
`sort`	type: string The key by which the list should be sorted.
`order`	type: string The order of the returned list.

Responses

200

Response body schema: application/json

destinations

type: array

items: object

required

destinationID

type: string

required

The destination UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

type

type: string

required

Type of the Destination, defines in which Algolia product the data will be stored.

One of: search, insights, flow, predict

name

type: string

required

An human readable name describing the object.

input

type: DestinationInput

required

One of:

DestinationIndexPrefix

indexPrefix

type: string

required

The prefix of the final index name.

DestinationIndexName

indexName

type: string

required

The index name to store data in.

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

authenticationID

type: string

pagination

type: object

required

`nbPages`	type: integer required
`page`	type: integer required
`nbItems`	type: integer required
`itemsPerPage`	type: integer required

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Create a destination

POST /1/destinations

Create a destination.

Request body

Accepts: application/json

type

type: string

required

One of: search, insights, flow, predict

name

type: string

required

input

type: DestinationInput

required

One of:

DestinationIndexPrefix

indexPrefix

type: string

required

The prefix of the final index name.

DestinationIndexName

indexName

type: string

required

The index name to store data in.

authenticationID

type: string

Responses

200

Response body schema: application/json

destinationID

type: string

required

The destination UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

name

type: string

required

An human readable name describing the object.

createdAt

type: string

required

Date of creation (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Search among destinations

POST /1/destinations/search

Search among destinations with a defined set of parameters.

Request body

Accepts: application/json

destinationIDs

type: array

items: string

required

Responses

200

Response body schema: application/json

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get a destination

GET /1/destinations/{destinationID}

Get the destination of the given destinationID.

Path parameter

destinationID

type: string

required

The destination UUID.

Example:destinationID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

destinationID

type: string

required

The destination UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

type

type: string

required

Type of the Destination, defines in which Algolia product the data will be stored.

One of: search, insights, flow, predict

name

type: string

required

An human readable name describing the object.

input

type: DestinationInput

required

One of:

DestinationIndexPrefix

indexPrefix

type: string

required

The prefix of the final index name.

DestinationIndexName

indexName

type: string

required

The index name to store data in.

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

authenticationID

type: string

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Update a destination

PATCH /1/destinations/{destinationID}

Update the destination of the given destinationID.

Path parameter

destinationID

type: string

required

The destination UUID.

Example:destinationID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Request body

Accepts: application/json

type

type: string

One of: search, insights, flow, predict

name

type: string

input

type: DestinationInput

One of:

DestinationIndexPrefix

indexPrefix

type: string

required

The prefix of the final index name.

DestinationIndexName

indexName

type: string

required

The index name to store data in.

authenticationID

type: string

Responses

200

Response body schema: application/json

destinationID

type: string

required

The destination UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

name

type: string

required

An human readable name describing the object.

updatedAt

type: string

required

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Delete a destination

DELETE /1/destinations/{destinationID}

Soft delete the destination of the given destinationID.

Path parameter

destinationID

type: string

required

The destination UUID.

Example:destinationID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

deletedAt

type: string

required

Date of deletion (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Observability

The observability API associates a run to a task execution.

GET	`/1/runs`	Get a list of runs
GET	`/1/runs/{runID}`	Get a run
GET	`/1/runs/{runID}/events`	Get a list of events
GET	`/1/runs/{runID}/events/{eventID}`	Get an event

Get a list of runs

GET /1/runs

Get a list of runs for the given query parameters, with pagination details.

Query parameter

`itemsPerPage`	type: integer The number of items per page to return.
`page`	type: integer The page number to fetch, starting at 1.
`status`	type: array items: string One of: `created`, `started`, `idled`, `finished`, `skipped` Filter the status of the runs.
`taskID`	type: string Filter by taskID. Example:`taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f`
`sort`	type: string The key by which the list should be sorted.
`order`	type: string The order of the returned list.

Responses

200

Response body schema: application/json

runs

type: array

items: object

required

runID

type: string

required

The run UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

appID

type: string

required

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

status

type: string

required

One of: created, started, idled, finished, skipped

progress

type: object

`expectedNbOfEvents`	type: integer
`receivedNbOfEvents`	type: integer

outcome

type: string

One of: success, failure

reason

type: string

Explains the result of outcome.

reasonCode

type: string

An identifier that pairs with the outcome reason.

One of: internal, critical, no_events, too_many_errors, ok, discarded

type

type: string

required

One of: reindex, update

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

required

Date of last update (RFC3339 format).

startedAt

type: string

Date of start (RFC3339 format).

finishedAt

type: string

Date of finish (RFC3339 format).

pagination

type: object

required

`nbPages`	type: integer required
`page`	type: integer required
`nbItems`	type: integer required
`itemsPerPage`	type: integer required

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get a run

GET /1/runs/{runID}

Get a single run for the given ID.

Path parameter

runID

type: string

required

The run UUID.

Example:runID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

runID

type: string

required

The run UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

appID

type: string

required

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

status

type: string

required

One of: created, started, idled, finished, skipped

progress

type: object

`expectedNbOfEvents`	type: integer
`receivedNbOfEvents`	type: integer

outcome

type: string

One of: success, failure

reason

type: string

Explains the result of outcome.

reasonCode

type: string

An identifier that pairs with the outcome reason.

One of: internal, critical, no_events, too_many_errors, ok, discarded

type

type: string

required

One of: reindex, update

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

required

Date of last update (RFC3339 format).

startedAt

type: string

Date of start (RFC3339 format).

finishedAt

type: string

Date of finish (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get a list of events

GET /1/runs/{runID}/events

Get a list of events associated to the given runID, for the given query parameters.

Path parameter

runID

type: string

required

The run UUID.

Example:runID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Query parameter

`itemsPerPage`	type: integer The number of items per page to return.
`page`	type: integer The page number to fetch, starting at 1.
`status`	type: array items: string One of: `created`, `started`, `retried`, `failed`, `succeeded` Filter the status of the events.
`type`	type: array items: string One of: `fetch`, `record`, `log`, `transform` Filter the type of the events.
`sort`	type: string The key by which the list should be sorted.
`order`	type: string The order of the returned list.

Responses

200

Response body schema: application/json

events

type: array

items: object

required

eventID

type: string

required

The event UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

runID

type: string

required

The run UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

parentID

type: string

The parent event, the cause of this event.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

status

type: string

required

One of: created, started, retried, failed, succeeded

type

type: string

required

One of: fetch, record, log, transform

data

type: object

Additional properties:

name*

type: any

publishedAt

type: string

required

Date of publish (RFC3339 format).

pagination

type: object

required

`nbPages`	type: integer required
`page`	type: integer required
`nbItems`	type: integer required
`itemsPerPage`	type: integer required

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get an event

GET /1/runs/{runID}/events/{eventID}

Get a single event for a specific runID.

Path parameter

runID

type: string

required

The run UUID.

Example:runID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

eventID

type: string

required

The event UUID.

Example:eventID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

eventID

type: string

required

The event UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

runID

type: string

required

The run UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

parentID

type: string

The parent event, the cause of this event.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

status

type: string

required

One of: created, started, retried, failed, succeeded

type

type: string

required

One of: fetch, record, log, transform

data

type: object

Additional properties:

name*

type: any

publishedAt

type: string

required

Date of publish (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Sources

A source describe the platform informations.

GET	`/1/sources`	Get a list of sources
POST	`/1/sources`	Create a source
POST	`/1/sources/search`	Search among sources
GET	`/1/sources/{sourceID}`	Get a source
PATCH	`/1/sources/{sourceID}`	Update a source
DELETE	`/1/sources/{sourceID}`	Delete a source

Get a list of sources

GET /1/sources

Get a list of sources for the given query parameters, with pagination details.

Query parameter

`itemsPerPage`	type: integer The number of items per page to return.
`page`	type: integer The page number to fetch, starting at 1.
`type`	type: array items: string One of: `bigcommerce`, `commercetools`, `json`, `csv`, `bigquery` The type of the sources to retrieve. Example:`type=commercetools,bigcommerce`
`authenticationID`	type: array items: string The authenticationIDs of the sources to retrieve. ‘none’ returns sources that doesn’t have an authentication. Example:`authenticationID=10000000-0a75-4000-a000-000000000001,none`
`sort`	type: string The key by which the list should be sorted.
`order`	type: string The order of the returned list.

Responses

200

Response body schema: application/json

sources

type: array

items: object

required

sourceID

type: string

required

The source UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

type

type: string

required

One of: bigcommerce, commercetools, json, csv, bigquery

name

type: string

required

input

type: SourceInput

required

One of:

SourceCommercetools

storeKeys

type: array

items: string

locales

type: array

items: string

Array of locales that must match the following pattern: ^[a-z]{2}(-[A-Z]{2})?$. For example ["fr-FR", "en"].

url

type: string

required

projectKey

type: string

required

SourceBigCommerce

storeHash

type: string

The store hash identifying the store the shopper is signing in to.

channel

type: object

id

type: integer

required

The ID of the bigcommerce channel.

currencies

type: array

items: string

An array of currencies for the given channel `ID`, a currency is a trigram string that represents the currency code.

Example:["usd", "eur"]

SourceJSON

`url`	type: string required The URL of the file.
`uniqueIDColumn`	type: string The name of the column that contains the unique ID, used as `objectID` in Algolia.
`method`	type: string One of: `GET`, `POST`

SourceCSV

url

type: string

required

The URL of the file.

uniqueIDColumn

type: string

The name of the column that contains the unique ID, used as `objectID` in Algolia.

mapping

type: object

Mapping of type for every column. For example {"myColumn": "boolean", "myOtherColumn": "json"}.

Additional properties:

name*

type: any

method

type: string

One of: GET, POST

delimiter

type: string

default: ,

The character used to split the value on each line, default to a comma (\r, \n, 0xFFFD, and space are forbidden).

SourceBigQuery

`projectID`	type: string required Project ID of the BigQuery Source.
`datasetID`	type: string required Dataset ID of the BigQuery Source.
`dataType`	type: string One of: `ga4`, `ga360`
`table`	type: string Table name (for default BQ).
`tablePrefix`	type: string Table prefix (for Google Analytics).
`customSQLRequest`	type: string Custom SQL request to extract data from the BigQuery table.

authenticationID

type: string

The authentication UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

pagination

type: object

required

`nbPages`	type: integer required
`page`	type: integer required
`nbItems`	type: integer required
`itemsPerPage`	type: integer required

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Create a source

POST /1/sources

Create a source.

Request body

Accepts: application/json

type

type: string

required

One of: bigcommerce, commercetools, json, csv, bigquery

name

type: string

required

input

type: SourceInput

required

One of:

SourceCommercetools

storeKeys

type: array

items: string

locales

type: array

items: string

Array of locales that must match the following pattern: ^[a-z]{2}(-[A-Z]{2})?$. For example ["fr-FR", "en"].

url

type: string

required

projectKey

type: string

required

SourceBigCommerce

storeHash

type: string

The store hash identifying the store the shopper is signing in to.

channel

type: object

id

type: integer

required

The ID of the bigcommerce channel.

currencies

type: array

items: string

An array of currencies for the given channel `ID`, a currency is a trigram string that represents the currency code.

Example:["usd", "eur"]

SourceJSON

`url`	type: string required The URL of the file.
`uniqueIDColumn`	type: string The name of the column that contains the unique ID, used as `objectID` in Algolia.
`method`	type: string One of: `GET`, `POST`

SourceCSV

url

type: string

required

The URL of the file.

uniqueIDColumn

type: string

The name of the column that contains the unique ID, used as `objectID` in Algolia.

mapping

type: object

Mapping of type for every column. For example {"myColumn": "boolean", "myOtherColumn": "json"}.

Additional properties:

name*

type: any

method

type: string

One of: GET, POST

delimiter

type: string

default: ,

The character used to split the value on each line, default to a comma (\r, \n, 0xFFFD, and space are forbidden).

SourceBigQuery

`projectID`	type: string required Project ID of the BigQuery Source.
`datasetID`	type: string required Dataset ID of the BigQuery Source.
`dataType`	type: string One of: `ga4`, `ga360`
`table`	type: string Table name (for default BQ).
`tablePrefix`	type: string Table prefix (for Google Analytics).
`customSQLRequest`	type: string Custom SQL request to extract data from the BigQuery table.

authenticationID

type: string

Responses

200

Response body schema: application/json

sourceID

type: string

required

The source UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

name

type: string

required

createdAt

type: string

required

Date of creation (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Search among sources

POST /1/sources/search

Search among sources with a defined set of parameters.

Request body

Accepts: application/json

sourceIDs

type: array

items: string

required

Responses

200

Response body schema: application/json

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get a source

GET /1/sources/{sourceID}

Get the source of the given sourceID.

Path parameter

sourceID

type: string

required

The source UUID.

Example:sourceID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

sourceID

type: string

required

The source UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

type

type: string

required

One of: bigcommerce, commercetools, json, csv, bigquery

name

type: string

required

input

type: SourceInput

required

One of:

SourceCommercetools

storeKeys

type: array

items: string

locales

type: array

items: string

Array of locales that must match the following pattern: ^[a-z]{2}(-[A-Z]{2})?$. For example ["fr-FR", "en"].

url

type: string

required

projectKey

type: string

required

SourceBigCommerce

storeHash

type: string

The store hash identifying the store the shopper is signing in to.

channel

type: object

id

type: integer

required

The ID of the bigcommerce channel.

currencies

type: array

items: string

An array of currencies for the given channel `ID`, a currency is a trigram string that represents the currency code.

Example:["usd", "eur"]

SourceJSON

`url`	type: string required The URL of the file.
`uniqueIDColumn`	type: string The name of the column that contains the unique ID, used as `objectID` in Algolia.
`method`	type: string One of: `GET`, `POST`

SourceCSV

url

type: string

required

The URL of the file.

uniqueIDColumn

type: string

The name of the column that contains the unique ID, used as `objectID` in Algolia.

mapping

type: object

Mapping of type for every column. For example {"myColumn": "boolean", "myOtherColumn": "json"}.

Additional properties:

name*

type: any

method

type: string

One of: GET, POST

delimiter

type: string

default: ,

The character used to split the value on each line, default to a comma (\r, \n, 0xFFFD, and space are forbidden).

SourceBigQuery

`projectID`	type: string required Project ID of the BigQuery Source.
`datasetID`	type: string required Dataset ID of the BigQuery Source.
`dataType`	type: string One of: `ga4`, `ga360`
`table`	type: string Table name (for default BQ).
`tablePrefix`	type: string Table prefix (for Google Analytics).
`customSQLRequest`	type: string Custom SQL request to extract data from the BigQuery table.

authenticationID

type: string

The authentication UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Update a source

PATCH /1/sources/{sourceID}

Update the source of the given sourceID.

Path parameter

sourceID

type: string

required

The source UUID.

Example:sourceID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Request body

Accepts: application/json

name

type: string

input

type: SourceUpdateInput

One of:

SourceUpdateCommercetools

storeKeys

type: array

items: string

Unique and immutable key of the referenced Store.

locales

type: array

items: string

Array of locales that must match the following pattern: ^[a-z]{2}(-[A-Z]{2})?$. For example ["fr-FR", "en"].

SourceJSON

`url`	type: string required The URL of the file.
`uniqueIDColumn`	type: string The name of the column that contains the unique ID, used as `objectID` in Algolia.
`method`	type: string One of: `GET`, `POST`

SourceCSV

url

type: string

required

The URL of the file.

uniqueIDColumn

type: string

The name of the column that contains the unique ID, used as `objectID` in Algolia.

mapping

type: object

Mapping of type for every column. For example {"myColumn": "boolean", "myOtherColumn": "json"}.

Additional properties:

name*

type: any

method

type: string

One of: GET, POST

delimiter

type: string

default: ,

The character used to split the value on each line, default to a comma (\r, \n, 0xFFFD, and space are forbidden).

SourceBigQuery

`projectID`	type: string required Project ID of the BigQuery Source.
`datasetID`	type: string required Dataset ID of the BigQuery Source.
`dataType`	type: string One of: `ga4`, `ga360`
`table`	type: string Table name (for default BQ).
`tablePrefix`	type: string Table prefix (for Google Analytics).
`customSQLRequest`	type: string Custom SQL request to extract data from the BigQuery table.

authenticationID

type: string

Responses

200

Response body schema: application/json

sourceID

type: string

required

The source UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

name

type: string

required

updatedAt

type: string

required

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Delete a source

DELETE /1/sources/{sourceID}

Soft delete the source of the given sourceID.

Path parameter

sourceID

type: string

required

The source UUID.

Example:sourceID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

deletedAt

type: string

required

Date of deletion (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Tasks

A Task describe how we fetch the data (onDemand, schedule, subscription) from a source and how we index it on the Algolia side.

GET	`/1/tasks`	Get a list of tasks
POST	`/1/tasks`	Create a task
POST	`/1/tasks/search`	Search among tasks
GET	`/1/tasks/{taskID}`	Get a task
PATCH	`/1/tasks/{taskID}`	Update a task
DELETE	`/1/tasks/{taskID}`	Delete a task
POST	`/1/tasks/{taskID}/run`	Run a task
PUT	`/1/tasks/{taskID}/enable`	Enable a task
PUT	`/1/tasks/{taskID}/disable`	Disable a task

Get a list of tasks

GET /1/tasks

Get a list of tasks for the given query parameters, with pagination details.

Query parameter

`itemsPerPage`	type: integer The number of items per page to return.
`page`	type: integer The page number to fetch, starting at 1.
`action`	type: array items: string One of: `replace`, `save` The action of the tasks to retrieve. Example:`action=save,replace`
`enabled`	type: boolean Whether the task is enabled or not.
`sourceID`	type: array items: string The sourceIDs of the tasks to retrive.
`destinationID`	type: array items: string The destinationIDs of the tasks to retrive.
`triggerType`	type: array items: string One of: `onDemand`, `schedule`, `subscription` The trigger type of the task. Example:`triggerType=onDemand,schedule`
`sort`	type: string The key by which the list should be sorted.
`order`	type: string The order of the returned list.

Responses

200

Response body schema: application/json

tasks

type: array

items: object

required

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

sourceID

type: string

required

The source UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

destinationID

type: string

required

The destination UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

trigger

type: Trigger

required

One of:

OnDemandTrigger

type

type: string

required

A task which is manually executed via the run task endpoint.

One of: onDemand

lastRun

type: string

The last time the scheduled task ran (RFC3339 format).

ScheduleTrigger

`type`	type: string required A task which is triggered by a schedule (cron expression). One of: `schedule`
`cron`	type: string required A cron expression that represent at which regularity the task should run. Example:`* * 1 * *`
`lastRun`	type: string The last time the scheduled task ran (RFC3339 format).
`nextRun`	type: string required The next scheduled run of the task (RFC3339 format).

SubscriptionTrigger

type

type: string

required

A task which is triggered by an external subscription (e.g. Webhook).

One of: subscription

input

type: TaskInput

One of:

OnDemandDateUtilsInput

`startDate`	type: string required The start date of the extraction (RFC3339 format).
`endDate`	type: string required The end date of the extraction (RFC3339 format).

ScheduleDateUtilsInput

timeframe

type: integer

required

The timeframe of the extraction, in number of days from today.

enabled

type: boolean

required

Whether the task is enabled or not.

action

type: string

required

The action to perform on the Algolia index.

One of: replace, save

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

pagination

type: object

required

`nbPages`	type: integer required
`page`	type: integer required
`nbItems`	type: integer required
`itemsPerPage`	type: integer required

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Create a task

POST /1/tasks

Create a task.

Request body

Accepts: application/json

sourceID

type: string

required

destinationID

type: string

required

trigger

type: TaskCreateTrigger

required

One of:

OnDemandTriggerInput

type

type: string

required

A task which is manually executed via the run task endpoint.

One of: onDemand

ScheduleTriggerInput

type

type: string

required

A task which is triggered by a schedule (cron expression).

One of: schedule

cron

type: string

required

A cron expression that represent at which regularity the task should run.

Example:* * 1 * *

SubscriptionTrigger

type

type: string

required

A task which is triggered by an external subscription (e.g. Webhook).

One of: subscription

action

type: string

required

One of: replace, save

enabled

type: boolean

input

type: TaskInput

One of:

OnDemandDateUtilsInput

`startDate`	type: string required The start date of the extraction (RFC3339 format).
`endDate`	type: string required The end date of the extraction (RFC3339 format).

ScheduleDateUtilsInput

timeframe

type: integer

required

The timeframe of the extraction, in number of days from today.

Responses

200

Response body schema: application/json

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

createdAt

type: string

required

Date of creation (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Search among tasks

POST /1/tasks/search

Search among tasks with a defined set of parameters.

Request body

Accepts: application/json

taskIDs

type: array

items: string

required

Responses

200

Response body schema: application/json

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Get a task

GET /1/tasks/{taskID}

Get the task of the given taskID.

Path parameter

taskID

type: string

required

The task UUID.

Example:taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

sourceID

type: string

required

The source UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

destinationID

type: string

required

The destination UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

trigger

type: Trigger

required

One of:

OnDemandTrigger

type

type: string

required

A task which is manually executed via the run task endpoint.

One of: onDemand

lastRun

type: string

The last time the scheduled task ran (RFC3339 format).

ScheduleTrigger

`type`	type: string required A task which is triggered by a schedule (cron expression). One of: `schedule`
`cron`	type: string required A cron expression that represent at which regularity the task should run. Example:`* * 1 * *`
`lastRun`	type: string The last time the scheduled task ran (RFC3339 format).
`nextRun`	type: string required The next scheduled run of the task (RFC3339 format).

SubscriptionTrigger

type

type: string

required

A task which is triggered by an external subscription (e.g. Webhook).

One of: subscription

input

type: TaskInput

One of:

OnDemandDateUtilsInput

`startDate`	type: string required The start date of the extraction (RFC3339 format).
`endDate`	type: string required The end date of the extraction (RFC3339 format).

ScheduleDateUtilsInput

timeframe

type: integer

required

The timeframe of the extraction, in number of days from today.

enabled

type: boolean

required

default: true

Whether the task is enabled or not.

action

type: string

required

The action to perform on the Algolia index.

One of: replace, save

createdAt

type: string

required

Date of creation (RFC3339 format).

updatedAt

type: string

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Update a task

PATCH /1/tasks/{taskID}

Update the task of the given taskID.

Path parameter

taskID

type: string

required

The task UUID.

Example:taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Request body

Accepts: application/json

destinationID

type: string

trigger

type: object

type

type: string

required

The type of the task reflect how it can be used: - onDemand: a task that runs manually - schedule: a task that runs regularly, following a given cron expression - subscription: a task that runs after a subscription event is received from an integration (e.g. Webhook).

One of: onDemand, schedule, subscription

input

type: TaskInput

One of:

OnDemandDateUtilsInput

`startDate`	type: string required The start date of the extraction (RFC3339 format).
`endDate`	type: string required The end date of the extraction (RFC3339 format).

ScheduleDateUtilsInput

timeframe

type: integer

required

The timeframe of the extraction, in number of days from today.

enabled

type: boolean

Responses

200

Response body schema: application/json

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

updatedAt

type: string

required

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Delete a task

DELETE /1/tasks/{taskID}

Soft delete the task of the given taskID.

Path parameter

taskID

type: string

required

The task UUID.

Example:taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

deletedAt

type: string

required

Date of deletion (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Run a task

POST /1/tasks/{taskID}/run

Run the task of the given taskID.

Path parameter

taskID

type: string

required

The task UUID.

Example:taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

runID

type: string

required

The run UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

createdAt

type: string

required

Date of creation (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Enable a task

PUT /1/tasks/{taskID}/enable

Enable the task of the given taskID.

Path parameter

taskID

type: string

required

The task UUID.

Example:taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

updatedAt

type: string

required

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Disable a task

PUT /1/tasks/{taskID}/disable

Disable the task of the given taskID.

Path parameter

taskID

type: string

required

The task UUID.

Example:taskID=6c02aeb1-775e-418e-870b-1faccd4b2c0f

Responses

200

Response body schema: application/json

taskID

type: string

required

The task UUID.

Example:6c02aeb1-775e-418e-870b-1faccd4b2c0f

updatedAt

type: string

required

Date of last update (RFC3339 format).

400

Bad request or request arguments.

Response body schema: application/json

message

type: string

Example:Invalid Application-Id or API-Key

Did you find this page helpful?