Developers

BolderBrain API

A read-only REST API over your organisation's assessment results and people directory. Every request is scoped to one organisation by the key you use, so there is nothing to pass in the body and nothing you can reach outside your own tenant.

Getting a key

Sign in as an organisation admin, open Settings → API keys, and create one. The key is shown once. Copy it then; it cannot be recovered, only revoked and replaced.

Authentication

Send the key as a bearer token on every request. Keys start with bb_live_.

curl https://bolderbrain.com/api/v1/me \
  -H "Authorization: Bearer bb_live_xxxxxxxxxxxxxxxx"

Base URL: https://bolderbrain.com/api/v1. All responses are JSON. Timestamps are ISO 8601 UTC.

GET/me

Check a key

Returns the organisation behind the key, the key's name, and the rate limit.

{
  "api_version": "v1",
  "organization": { "id": "clx...", "name": "Acme India", "slug": "acme-india" },
  "key": { "id": "clk...", "name": "HRIS nightly sync" },
  "rate_limit": { "requests_per_minute": 120 }
}

GET/attempts

List assessment attempts

One page of attempts across all three assessment types, newest first. Filter by type (iq, eq, psychometric), status (IN_PROGRESS, COMPLETED), and a date window with from / to.

curl "https://bolderbrain.com/api/v1/attempts?type=iq&status=COMPLETED&from=2026-10-01&limit=50" \
  -H "Authorization: Bearer bb_live_xxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "clx...",
      "type": "iq",
      "userId": "clu...",
      "status": "COMPLETED",
      "startedAt": "2026-10-28T09:14:02.000Z",
      "submittedAt": "2026-10-28T09:41:55.000Z",
      "score": 118,
      "percentile": 88,
      "band": "Above average"
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

score is the standard score for cognitive ability and the composite for emotional intelligence. The psychometric profile has no single score, so score is null and band carries its summary line.

GET/attempts/{type}/{id}

Read one attempt

The attempt plus its scored result: percentile and confidence interval for cognitive ability, domain scores for emotional intelligence, trait percentiles and validity flags for the psychometric profile.

curl https://bolderbrain.com/api/v1/attempts/eq/clx123 \
  -H "Authorization: Bearer bb_live_xxxxxxxxxxxxxxxx"

Only scored attempts carry a result object. An attempt still in progress returns "result": null.

GET/people

List the organisation roster

Members of the organisation with their role, department and job title. Filter with department or active=true|false.

{
  "data": [
    {
      "id": "clm...",
      "user_id": "clu...",
      "name": "Anita Rao",
      "email": "[email protected]",
      "role": "MANAGER",
      "department": "Operations",
      "job_title": "Regional Manager",
      "career_level": "M1",
      "is_active": true,
      "account_active": true,
      "joined_at": "2026-04-02T06:12:44.000Z"
    }
  ],
  "pagination": { "limit": 25, "next_cursor": "eyJ...", "has_more": true }
}

Pagination

Every list endpoint takes limit (1 to 100, default 25) and returns next_cursor. Pass it back as ?cursor= for the next page. Cursors are opaque; do not parse them. When has_more is false you are at the end.

Errors

Failures return a non-2xx status and a stable code:

{ "error": { "code": "invalid_api_key", "message": "A valid API key is required..." } }

401 invalid_api_key — missing, malformed, unknown or revoked key.
400 invalid_type, invalid_status, invalid_date, invalid_cursor — a query parameter was rejected.
404 not_found — no such attempt in this organisation.
429 rate_limited — 120 requests per minute per key. Check Retry-After.

Data and security

Keys are organisation-wide and read-only. There is no write endpoint in v1.
Only a SHA-256 hash of each key is stored. Revoking a key takes effect on the next request.
Every request is logged against the key that made it, so an admin can see last use in Settings.
Person names and emails are decrypted for the response because they are your records. Treat a key as you would a password to your HR system.

Need something the v1 endpoints do not cover, like webhooks on completion or a report PDF? Write to [email protected] and tell us what you are building.