Docs / API

API reference

Everything the CLI and MCP server do goes through one HTTP API, and you can call it directly from any language. The contract is published as an OpenAPI 3.1 spec, so you can generate a typed client from it or read it in the rendered reference.

• Rendered API reference: every route with its request and response shapes.
• Raw OpenAPI JSON: https://api.beryl.so/api/v1/openapi.json

Authentication

Send a token as Authorization: Bearer <token> on every request. A personal access token (beryl_pat_...) works on every route; create one under Account, API tokens in the web app, or with beryl tokens create.

A project CI token (beryl_ci_..., see CI integration) works only on the routes the spec marks with x-beryl-ci-token: triggering a run and following its progress and results, listing tests, and test creation jobs, all for its one project.

curl -H "Authorization: Bearer $BERYL_TOKEN" \
  https://api.beryl.so/api/v1/workspaces/

How the API is laid out

Every path is under https://api.beryl.so/api/v1. Almost all of them are scoped by workspace and project, as in /workspaces/{workspace_id}/projects/{project_id}/runs. List your workspaces first, then the projects inside one. Routes are grouped by area: workspaces, projects, environments, tests, jobs, runs, test accounts, mailboxes, config, CI and tokens.