Authenticate
- Workspace API token. A workspace owner or admin mints one in Settings → API tokens and chooses its scopes. Send it as
Authorization: Bearer tb_…. A token reaches only its own workspace and only the endpoints its scopes allow. An expired or revoked token is refused on its next request, and so is a token whose creator is no longer an owner or admin of the workspace — mint integration tokens from an account that will stay. - Signed-in user. The web app's session, or a user's Supabase access token as a Bearer token. A user in several workspaces names one with the
X-TerraBrains-Orgheader.
Endpoints
- GET /api/v1/projectstoken scope: projects:read
The workspace’s projects, newest first (limit ≤ 100).
- GET /api/v1/projects/{projectId}/boreholestoken scope: boreholes:read
A project’s boreholes with status, depths and position (null when none is recorded).
- GET /api/v1/analysestoken scope: analysis:run
The analysis catalogue, with the Store pack and api_runnable for each entry.
- POST /api/v1/analyses/{slug}/runtoken scope: analysis:run
Compute one config analysis from { "inputs": { … } } and return the result. Not saved.
- GET /api/v1/projects/{projectId}/runssigned-in user only (no API token)
A project’s saved analysis runs.
- POST /api/v1/projects/{projectId}/runssigned-in user only (no API token)
Save a computed run to the project record (server-verified outputs).
- GET /api/v1/runs/{runId}signed-in user only (no API token)
One saved analysis run, in full.
Example
curl -H "Authorization: Bearer $TERRABRAINS_TOKEN" \
https://terrabrains.ai/api/v1/projects
curl -X POST -H "Authorization: Bearer $TERRABRAINS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"inputs": {"slope_angle_deg": 20}}' \
https://terrabrains.ai/api/v1/analyses/infinite-slope/runLimits and errors
- 120 requests per 60 seconds per workspace for each class of request (reads, saves, analysis runs). Every response carries
X-RateLimit-*headers; over the limit the API answers 429 withRetry-After. - Analysis runs check the workspace's plan, validate every input against the analysis's declared fields, and are not saved. Omitted inputs take the form's default and are listed in
defaulted. Store-pack analyses, and analyses with a bespoke input form, are not runnable through the API;api_runnablein the catalogue says which are. - A run computes for at most 20 seconds (past that it is stopped: 422
compute_timeout), takes a body of up to 256 KB, and a workspace may have 2 runs computing at once (429run_in_progress). - Errors are JSON —
{"error": "<code>", "message": "…"}— for example 401invalid_token, 403insufficient_scope, 404 for anything outside the workspace, and 429too_many_failed_tokensafter repeated invalid tokens. - Webhooks and client SDKs are next on the roadmap; AGS and DIGGS travel by export.