This repository contains the API specs for the Typesense HTTP API.

Some of the client libraries use the specs from this repo to generate types.

You can use Swagger Editor to view/edit the API spec files.

Clone this repo, and then from the root of this repo, run:

docker run -p 8080:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/openapi.yml swaggerapi/swagger-editor

Now visit http://localhost:8080 in your browser to view the spec file in your browser.

Once you've made edits, click on File -> Save as YAML. Then copy that file into this repo and rename the file to use a .yml extension.

src/ extracts the API's routes and parameters from the highest-versioned stable Typesense release (not GitHub's "latest" flag, which a backport can take) into output/, so openapi.yml only gains what has shipped. RC versions are skipped, set source_branch in config.json to read a branch or tag instead. A nightly workflow opens a pull request when they change, with a report linking each change to its source. Update openapi.yml on that branch, then merge it, even if nothing needed updating: closing it only defers the report to the next run.

The project uses Bun:

bun install --frozen-lockfile
bun test
bun run check
bun run lint

# Extract. A token is optional, but avoids the anonymous GitHub API rate limit.
GITHUB_TOKEN=$(gh auth token) bun src/cli.ts extract --config ./config.json

# After changing the extractor, regenerate output/ from the release it records. Only the
# bot pull request moves output/ to a newer release, so openapi.yml gets reviewed first.
bun src/cli.ts extract --source-branch "$(jq -r .sourceBranch output/typesense_api_spec.json)"

# Compare two extracted specs.
bun src/cli.ts semantic-diff --previous old.json --next new.json --markdown-output diff.md

To also run the integration tests, which extract from real source without using the network, clone Typesense into the gitignored tmp/ folder. They skip without it.

git clone https://github.com/typesense/typesense tmp/typesense