REST · v2
API reference
The Shoal REST API manages projects, flags, environments and webhooks. It uses JSON over HTTPS, predictable resource URLs and standard HTTP status codes.
Base URL
https://api.shoal.dev/v2
Authentication
Authenticate with an API token in the Authorization header. Create tokens under Account → API tokens. Tokens carry your permissions — keep them on the server.
Pagination
List endpoints return up to limit items (default 20, max 100) and a next cursor. Pass it as cursor to fetch the next page.
Terminal
curl https://api.shoal.dev/v2/projects \
-H "Authorization: Bearer $SHOAL_TOKEN"TypeScript
import { Shoal } from "@shoal/api";
const api = new Shoal(process.env.SHOAL_TOKEN);
const projects = await api.projects.list();Python
from shoal import Shoal
api = Shoal(os.environ["SHOAL_TOKEN"])
projects = api.projects.list()Errors
Errors return a JSON body with a machine-readable code and a human-readable message.
- 400
- Invalid request — check the error message for the field.
- 401
- Missing or invalid API token.
- 403
- The token lacks permission for this project.
- 404
- The resource doesn’t exist.
- 409
- Conflict — e.g. a flag key already exists.
- 429
- Rate limited — 100 requests per 10 s per token. Retry after the Retry-After header.