OpenAPI specification

Machine-readable descriptions of the task API, one per hostname. Import them into a client generator, an HTTP client, or anything that reads OpenAPI 3.1.

Three documents describing one gateway. They differ only in the servers block and in what they say about endpoints that hostname answers for. Pick the one matching the base URL you will call, so a generated client needs no further configuration.

Generating a client

npx @openapitools/openapi-generator-cli generate \
  -i https://app.legibl.io/docs/spec/openapi.json \
  -g php -o ./legibl-client

Every operation carries an operationId, so generated method names are createTask, getTaskResult and getBalance rather than something derived from the path.

Two things the specification says that a reader should not skim

Every response is HTTP 200, including failures, which are carried in the body as errorId: 1 with an errorCode. That is what the client libraries in this market expect, and several of them raise on a non-2xx before reading the body. It is also why no 4xx responses are documented: none are returned, and describing a status this API does not produce would be worse than the linter warning it avoids.

Four task types are implemented and everything else is refused with ERROR_TASK_NOT_SUPPORTED. The specification enumerates them rather than leaving the field open, so a generated client carries the real list.

Keeping it honest

The documents are generated by spec/generate.py, which reads the shapes out of the gateway's own source rather than restating them. Regenerate after changing an endpoint, a task type or an error code.