Skip to main content
Documentation

Getting startedwith TerraBrains.

Sign up, run the validator, verify a signed report, and understand how the core concepts — workspace access, audit chain, AI sources — fit together.

The whole manual as one PDF, alongside the web guides below. Every analysis also carries its own method guide in the app.

Take a guided tour

A step-by-step guide stays beside you on every screen. You can end it any time.

Set up your first project

From an empty workspace to a signed report: a project, a borehole, your first analysis and a report.

Import your existing project

Bring an AGS file, spreadsheets or a PDF report; the importer extracts boreholes, samples and lab results and you confirm them.

Follow a complete task

Record the first borehole
  1. Create or open a project, then open its Boreholes section. Add a borehole and enter the observed location and depth information.
  2. Add depth-indexed layers, SPT readings and samples as measured. Review the log and save.
  3. On a phone, check queued uploads and sync errors after reconnecting. Keep the device data until the records have uploaded.
Enter the first laboratory test
  1. Open the source sample and select the test and applicable method.
  2. Replace example/default observations with measured readings, including units and specimen details.
  3. Inspect the derived result and any warnings, confirm the equipment/calibration and custody record, then save for review.
Run the first calculation
  1. Open a free calculator or select an analysis inside a project. Choose the design code and method independently where offered.
  2. Replace the sample inputs with project observations. Check units, scope and groundwater assumptions.
  3. Read warnings, result references and figures. Load a published example to inspect the method, then return to your project inputs.
Review and issue a report
  1. Review the source records, analysis inputs and cited outputs. Resolve unsupported or flagged AI draft text.
  2. Ask the authorised reviewer to complete the review/signing workflow and its second-factor check.
  3. Issue the signed PDF. Use its QR code or upload it to the public verifier to check integrity. A matching digest does not replace professional review.
Recover from a sync interruption
  1. Keep the app and local device data available. Do not uninstall or clear storage while records are queued.
  2. Reconnect and inspect the pending/failed sync items. Read the error before retrying.
  3. Avoid concurrent offline edits to the same record. If a conflict or repeated failure remains, send support the app version and error, without passwords or authentication codes.
Invite colleagues with the right access
  1. An authorised workspace owner or administrator opens the team/access controls and invites the colleague.
  2. Choose the role and project access needed for their work; paid engineering seats and free capture seats have different permissions.
  3. The recipient accepts the invitation using the intended account. Confirm the workspace and project access before entering customer data.
API · 03

The public API, version 1.

A workspace-scoped REST API: read projects and boreholes, list the catalogue and run analyses from your own scripts. Every endpoint is listed below. Themachine-readable contract is the OpenAPI 3.1 document.

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-Org header.

Endpoints

  • GET /api/v1/projects
    token scope: projects:read

    The workspace’s projects, newest first (limit ≤ 100).

  • GET /api/v1/projects/{projectId}/boreholes
    token scope: boreholes:read

    A project’s boreholes with status, depths and position (null when none is recorded).

  • GET /api/v1/analyses
    token scope: analysis:run

    The analysis catalogue, with the Store pack and api_runnable for each entry.

  • POST /api/v1/analyses/{slug}/run
    token scope: analysis:run

    Compute one config analysis from { "inputs": { … } } and return the result. Not saved.

  • GET /api/v1/projects/{projectId}/runs
    signed-in user only (no API token)

    A project’s saved analysis runs.

  • POST /api/v1/projects/{projectId}/runs
    signed-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/run

Limits 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 with Retry-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_runnable in 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 (429 run_in_progress).
  • Errors are JSON — {"error": "<code>", "message": "…"} — for example 401 invalid_token, 403 insufficient_scope, 404 for anything outside the workspace, and 429 too_many_failed_tokens after repeated invalid tokens.
  • Webhooks and client SDKs are next on the roadmap; AGS and DIGGS travel by export.

Try it on your own boreholes.

Start free, import a borehole log or an AGS file, and follow these guides in the app.