---
title: "Create external engine"
method: POST
path: "/api/external-engine"
tags: ["External engine"]
---

# Create external engine

`POST /api/external-engine`

Registers a new external engine for the user. It can then be selected
and used on the analysis board.
After registering, the provider should start waiting for analyis requests.

## Request body

- ExternalEngineRegistration
  - `name` string, required — Display name of the engine.
  - `maxThreads` integer, required — Maximum number of available threads.
  - `maxHash` integer, required — Maximum available hash table size, in MiB.
  - `variants` UciVariant[] — Optional list of supported chess variants.
  - `providerSecret` string, required — A random token that can be used to [wait for analysis requests](#tag/external-engine/POST/api/external-engine/work) and provide analysis. The engine provider should securely generate a random string. The token will not be readable again, even by the user. The analysis provider can register multiple engines with the same token, even for different users, and wait for analysis requests from any of them. In this case, the request must not be made via CORS, so that the token is not revealed to any of the users.
  - `providerData` string — Arbitrary data that the engine provider can use for identification or bookkeeping. Users can read this information, but updating it requires knowing or changing the `providerSecret`.

## Response `200`

The registered engine.

- ExternalEngine
  - `id` string, required — Unique engine registration ID.
  - `name` string, required — Display name of the engine.
  - `clientSecret` string, required — A secret token that can be used to [*request* analysis](#tag/external-engine/POST/api/external-engine/{id}/analyse) from this external engine.
  - `userId` string, required — The user this engine has been registered for.
  - `maxThreads` integer, required — Maximum number of available threads.
  - `maxHash` integer, required — Maximum available hash table size, in MiB.
  - `variants` UciVariant[], required — List of supported chess variants.
  - `providerData` string, nullable — Arbitrary data that the engine provider can use for identification or bookkeeping. Users can read this information, but updating it requires knowing or changing the `providerSecret`.

---

[API](https://skmtc.net/lichess/apis/lichess-org-api-reference.md) · [All operations](https://skmtc.net/lichess/apis/lichess-org-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lichess/lichess-org-api-reference/versions/1425db81eb3b/schema)