Brain Garden API Docs

Public endpoints for integrating with Brain Garden Creativity+. Use these routes to list models, generate enhanced content, and manage authentication. App-internal endpoints (e.g., chats UI) are intentionally excluded here.

Quick start

Base URL
https://braingarden.world
Auth headers
  • Brain Garden API key:
    X-Bg-Api-Key
  • BYOK (per-request):
    X-Byok-Api-Key
    X-Byok-Provider

Supported BYOK providers:
openai
anthropic
google
x-ai
mistralai (alias: mistral)

Meta

GET /health

Service health and OpenRouter reachability.

curl -s https://braingarden.world/health

Models

GET /v1/models?byok=false

Curated, server-supported list from configuration.

curl -s https://braingarden.world/v1/models?byok=false

GET /v1/models?byok=true

Requires Authorization or X-Bg-Api-Key. Returns models for providers you have stored BYOK keys for.

curl -s https://braingarden.world/v1/models?byok=true \
+  -H "X-Bg-Api-Key: bg_cpb_xxx"

Generation

POST /v1/generate

Body fields:

  • prompt (string, required)
  • model (string, optional)
  • format ("markdown" | "json"; default markdown)
  • speculation, randomness, ideas (0–100 sliders)
  • byok_api_key, byok_provider (optional; provider required if key supplied)
  • include_raw (bool, default true), raw_complete (bool)
  • second_pass_model (string), delta_enhance (bool)

Headers (optional): X-Bg-Api-Key for server-issued key; X-Byok-Api-Key and X-Byok-Provider to bill to your provider key; or use Authorization to bind usage and profiles.

curl -s -X POST https://braingarden.world/v1/generate \
+  -H "Content-Type: application/json" \
+  -H "X-Bg-Api-Key: bg_cpb_xxx" \
+  # optional BYOK (instead of X-Bg-Api-Key)
  # -H "X-Byok-Api-Key: sk-..." \
+  # -H "X-Byok-Provider: openai" \
+  -d '{
    "prompt": "Write a product launch plan.",
    "model": "openai/gpt-5",
    "format": "markdown",
    "speculation": 30,
    "randomness": 35,
    "ideas": 60
  }'
Response
{
  "text": "...enhanced markdown or JSON...",
  "metadata": {
    "model": "openai/gpt-5",
    "usage": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 },
    "controls": { /* resolved slider values */ },
    "graph": { /* enrichment metadata */ },
    "structure": { /* headings, format */ }
  },
  "raw_output": { "model": "openai/gpt-5", "text": "..." },
  "timings_ms": { "preprocess_and_graph": 0, "first_pass": 0, "second_pass": 0, "postprocess": 0 },
  "chat": { "chat_id": null, "message_id": null }
}

Rate limiting: short bursts allowed; roughly ~30 req/min per client IP.

Identity & Keys

GET /v1/auth/whoami

Auth with Authorization or X-Bg-Api-Key.

curl -s https://braingarden.world/v1/auth/whoami -H "X-Bg-Api-Key: bg_cpb_xxx"

POST /v1/auth/issue-key

Issue a Brain Garden API key bound to the authenticated user.

curl -s -X POST https://braingarden.world/v1/auth/issue-key \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

GET /v1/auth/keys

List your Brain Garden API keys.

curl -s https://braingarden.world/v1/auth/keys \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

DELETE /v1/auth/keys/{key_id}

curl -s -X DELETE https://braingarden.world/v1/auth/keys/KEY_ID \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

PATCH /v1/auth/keys/{key_id}

Update label and/or expires_at via query, e.g. ?label=Server%20Key.

curl -s -X PATCH "https://braingarden.world/v1/auth/keys/KEY_ID?label=Server%20Key" \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

Provider BYOK Keys

Store provider API keys to enable byok=true model filtering or automatic key resolution during generation.

GET /v1/keys

curl -s https://braingarden.world/v1/keys \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

POST /v1/keys

JSON body: { provider: string, key: string }

curl -s -X POST https://braingarden.world/v1/keys \
+  -H "Authorization: Bearer $SUPABASE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"openai","key":"sk-..."}'

GET /v1/keys/{key_id}

Reveal a stored provider key (access restricted to your account).

curl -s https://braingarden.world/v1/keys/KEY_ID \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

DELETE /v1/keys/{key_id}

curl -s -X DELETE https://braingarden.world/v1/keys/KEY_ID \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

Usage

GET /v1/usage/me

Requires Authorization. Returns plan, counters, and limits for the current billing period.

curl -s https://braingarden.world/v1/usage/me \
+  -H "Authorization: Bearer $SUPABASE_TOKEN"

Notes

  • Errors return JSON shape { detail: string } with appropriate HTTP status.
  • When a BYOK key is present, model calls are billed to your provider key; otherwise, platform credits are used.
  • MCP server details will be added here in a future update.

Need Support?

If you couldn't find the answer to your question,
feel free to contact support.