The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Skip to main content

Add a new API client


Make sure to first setup the repository tooling to ease your journey!

Adding a new API client requires some manual steps in order to have a properly working client:

  1. Writing specs
  2. Configuring the generator
  3. Generate the client
  4. Adding tests

1. Writing specs

We recommend to have a look at existing spec files.

The bundled folder is automatically generated, manual changes shouldn't be done in these files.


  • Endpoints: Each file in the paths folder should contain operationIds for a single endpoint, multiple methods are allowed.
  • File name:
    • When the path file only contain one method (e.g. GET), we name the file after the operationId
    • When multiple methods are present (e.g. PUT and DELETE), we pick a more generic name that is related to the endpoint itself.
  • Description/Summary: operationIds must have both description and summary.
  • Complex objects: Complex objects (nested arrays, nested objects, oneOf, allOf, etc.) must be referenced ($ref) in the operationId file and not inlined. This is required to provide a accurate naming and improve readability.

common spec folder

The common folder hosts properties that are common to Algolia and/or used in multiple clients.

<clientName> spec folder

Example with the search client spec

spec.yml file

The spec.yml file is the entry point of the client spec, it contains servers, paths and other specific information of the API. We recommend to copy an existing spec.yml file to get started.

<clientName>/common folder

Same as the common folder but only related to the current client.

<clientName>/paths folder

Path definition of the paths defined in the spec file. See guidelines.


Force the name of a requestBody

Detailed issue

In some cases, you can encounter wrongly named requestBody from the specs, which could be due to:

The x-codegen-request-body-name property can be added at the root of the spec, to force the name of the generated requestBody property.

You can find an example of this implementation on this PR.

Send additional options to the template

You might want to send additional information to the generators. To do so, you can add parameters starting with an x- at the root level of your spec, which will be available in the mustache template under the vendorExtensions object.

Example in the search.yml spec and how it is used in a mustache file.

2. Configuring the generator

The generator follows its own configuration file named config/openapitools.json


config/openapitools.json and config/clients.config.json hosts the configuration of all of the generated clients with their available languages and extra information.


Generators are referenced by key with the following pattern <languageName>-<clientName>. You can copy an existing object of a client and replace the <clientName> value with the one you'd like to generate.

Below are the options you need to make sure to define for your client, other options are automatically added by our generator.

outputopenapitools.jsonAllThe output path of the client.
packageVersionclients.config.jsonAllThe version you'd like to publish the first iteration of the generated client. It will be automatically incremented.
gitRepoIdclients.config.jsonAllThe name of the repository.
folderclients.config.jsonAllThe path to the folder that will host the generated code.
modelFolderclients.config.jsonAllThe path to the model folder that will host the generated code.
apiFolderclients.config.jsonAllThe path to the api folder that will host the generated code.
customGeneratorclients.config.jsonAllThe name of the generator used to generate code.

3. Generate the client

You can find all the commands in the CLI > clients commands page and CLI > specs commands page.

4. Adding tests with the Common Test Suite

Clients needs to be tested, you can read more in the Common Test Suite guide.