DEVELOPERS

BrainVault API

Connect BrainVault to the rest of your tools. The API reads and adds ideas and comments in one workspace, and sends events the moment they happen. It is what the BrainVault app for Zapier uses; with Zapier you can connect thousands of apps without writing code.

Authentication

Every request needs a workspace API key. A workspace administrator creates one in BrainVault under Settings → Integrations → Zapier → Create API key. The key is shown once; it can be revoked there at any time, which also removes its hook subscriptions. API keys are available on the Business and Enterprise plans.

Send the key as a bearer token (or in an X-API-Key header):

curl https://brainvault.thegrowthsystem.co.za/api/v1/me \
  -H "Authorization: Bearer bv_live_…"

Base address: https://brainvault.thegrowthsystem.co.za/api/v1. Requests and responses are JSON (send Content-Type: application/json). All times are ISO 8601 in UTC. A key only ever sees its own workspace.

Endpoints

GET/me

The workspace the API key belongs to. Use it to check a key.

Returns 200 with { "workspace": { "id", "name" } }.

GET/ideas

Recent ideas in the workspace, newest first. Drafts are never included.

Query	Meaning
limit	Optional. 1 to 100; default 25.

Returns 200 with an array of ideas.

{
  "id": "8a1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "title": "Solar pre-heating for the staff canteen",
  "problem": "The canteen's water heaters run all morning on grid power.",
  "solution": "Pre-heat the water with rooftop solar collectors.",
  "who_benefits": "Facilities and the canteen team",
  "status": "active",
  "stage": "Evaluation",
  "stage_key": "evaluation",
  "department": "Facilities",
  "author": "Thandi Mokoena",
  "score": 7.4,
  "created_at": "2026-11-11T08:30:00.000Z",
  "url": "https://brainvault.thegrowthsystem.co.za/ideas/8a1f2c3d-…"
}

POST/ideas

Submits a new idea. It is submitted in the name of the administrator who created the key, starts in the first stage of the pipeline and counts towards the plan's active-idea limit.

Field	Meaning
title	Required. Up to 200 characters.
problem	Optional. The problem or opportunity.
solution	Optional. The idea itself.
who_benefits	Optional.
department	Optional. Up to 120 characters.

Returns 201 with the new idea. 422 if the title is missing; 403 if the plan's idea limit is reached.

GET/ideas/{id}

One idea.

Returns 200 with the idea, or 404 if it isn't in this workspace.

POST/ideas/{id}/comments

Adds a comment to an idea, in the name of the administrator who created the key. People following the idea are notified.

Field	Meaning
body	Required. The comment, up to 5,000 characters.

Returns 201 with { "id", "idea_id", "body", "created_at" }.

POST/hooks

Subscribes a Zapier hook address to an event. BrainVault then posts each matching event to it as it happens. Only Zapier hook addresses (https://hooks.zapier.com/…) are accepted.

Field	Meaning
event	Required. One of the events below.
target_url	Required. The Zapier hook address.

Returns 201 with { "id", "event", "target_url" }. At most 200 subscriptions per key.

DELETE/hooks/{id}

Removes a subscription made with this key.

Returns 204.

GET/samples

Up to three recent real examples of an event, in exactly the shape the hook sends.

Query	Meaning
event	Required. One of the events below.

Returns 200 with an array of events.

{
  "id": "idea.moved:8a1f2c3d-…:2026-11-11T09:00:00.000Z",
  "event": "idea.moved",
  "occurred_at": "2026-11-11T09:00:00.000Z",
  "to_stage": "Evaluation",
  "idea": { …an idea, as above… }
}

Events

Each event is posted as JSON to every subscribed hook address, with the idea attached. The id is unique per event, so a receiver can ignore repeats. If a hook address answers 410 Gone, BrainVault removes that subscription. Anonymous ideas are sent without an author.

Event	When
idea.created	Someone submits an idea.
idea.moved	An idea moves to another stage. Includes to_stage.
decision.recorded	The innovation council records a decision. Includes decision: approved, on_hold, needs_info or rejected.
evaluation.submitted	Someone submits an evaluation of an idea.
idea.completed	An idea is marked as completed.

Errors

Errors come back as { "error": "…" } with a plain-language message.

Status	Meaning
401	The API key is missing, wrong or revoked.
403	The workspace's plan doesn't allow this (for example, the idea limit).
404	No such idea in this workspace.
422	Something in the request is missing or invalid; the message says what.
429	Too many hook subscriptions for this key.

Help

Questions or problems: see Support. How BrainVault looks after your data is set out in the privacy policy and security overview.