BearForge API · Early Access

The first publicly available Skill is Bear Brain. This page shows how to call it. Other Skills are listed in the Console → Skills tab; their endpoints are not wired in this round.

First available Skill: Bear Brain

Bear Brain returns a 5-block structured chat response. The wrapper endpoint POST /api/skills/bear-brain/chat delegates to the same handler that powers the existing POST /api/bear/chat route; both share the Guest quota bucket so you cannot multiply your daily allowance by switching paths.

Endpoint

POST https://bearforge.io/api/skills/bear-brain/chat
Content-Type: application/json

Request

{
  "message": "Can I build an ADU on my property?",
  "project_id": null,
  "member_no": null,
  "metadata": {}
}

Response (success)

{
  "ok": true,
  "skill": "bear_brain",
  "framework_only": false,
  "preliminary_only": true,
  "locked_outputs": {
    "pdf": true,
    "dwg": true,
    "dxf": true,
    "svg": true,
    "permit_ready": true,
    "verified_zoning_final": true,
    "final_setback": true
  },
  "result": { ...5-block Bear Brain response... }
}

Example curl (anonymous, Guest quota)

curl -s -X POST https://bearforge.io/api/skills/bear-brain/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Can I build an ADU on my property?"}'

Example curl (with API key)

For external developer integrations, send your API key via the Authorization: Bearer header:

curl -X POST https://bearforge.io/api/skills/bear-brain/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bf_test_xxx" \
  -d '{"message":"Can I build an ADU on my property?"}'

API key is optional for website / session testing. If you are signed in to BearForge in your browser, your session cookie is sufficient for hitting the Skill from the same site. External developer integrations should use an API key via the Authorization header.

API key error responses

When the Authorization header is present but invalid, the wrapper fails closed without touching the Bear Brain handler or consuming any Guest quota. Responses use a structured error envelope:

HTTP 401 / 403
{
  "ok": false,
  "error": "invalid_api_key" | "revoked_api_key" | "missing_scope" | "malformed_authorization",
  "message": "Invalid or unauthorized BearForge API key.",
  "contact": "team@bearforge.ai"
}

malformed_authorization — the header is not Bearer <raw_key>, or the prefix is not bf_test_ / bf_live_. HTTP 401.
invalid_api_key — the key value is unknown to BearForge. HTTP 401.
revoked_api_key — the key exists but has been revoked. HTTP 401.
missing_scope — the key is active but does not carry the bear_brain:chat scope. HTTP 403.

Authentication

Session-based (website)

For the website itself, the magic-link auth session is sufficient. Sign in at /login, complete the magic-link callback, and the session cookie is attached automatically to subsequent requests.

API key (early access)

API key creation is in framework form in v1. Sign in first, then use the API Keys tab in the Console or POST directly:

POST /api-console/keys/create
Content-Type: application/json

{
  "scopes": ["bear_brain:chat", "pricing:estimate"],
  "label": "my first key",
  "mode": "test"
}

The raw key is returned exactly once. Store it client-side immediately — this endpoint will not replay the value. Keys are prefixed bf_test_. Only the SHA-256 hash is persisted server-side; revoked keys cannot be used.

Anonymous key creation is not permitted. The POST /api-console/keys/create endpoint returns 401 with error: sign_in_required when there is no session.

Other Skills (catalog)

The Skills catalog is published at GET /api/skills/status — no auth required:

curl -s https://bearforge.io/api/skills/status

Bear Brain is available. Bear Pricing is preview (no checkout, see /api/pricing/estimate). Bear Zoning, Bear Designer, Bear Printer, Bear PE are locked / reserved — listed for transparency but with no callable endpoint in v1.

Disclaimers

Preliminary guidance only. BearForge output is not a professional opinion. Final zoning, code, permit, design, and construction decisions must be verified with the applicable jurisdiction and licensed professionals.
No permit-ready output. The permit_ready_enabled flag is hard-coded to false.
No PDF/DWG/DXF/SVG export. The Bear Printer Skill is locked; pdf_dwg_dxf_svg_enabled is false.
No approval guarantee. BearForge does not promise any planning, zoning, or building-department outcome.
No verified-zoning final result. verified_zoning_enabled is false.
No final-setback certification. final_setback_enabled is false.
No licensed engineer / architect stamp. All outputs are unsigned candidate-level guidance.

Status surface

GET https://bearforge.io/api/skills/status

{
  "ok": true,
  "api_console_enabled": true,
  "first_launch_skill": "bear_brain",
  "available_skills": ["bear_brain"],
  "locked_skills": ["bear_zoning", "bear_designer", "bear_printer", "bear_pe"],
  "billing_enabled": false,
  "stripe_enabled": false,
  "printer_gate_locked": true,
  "permit_ready_enabled": false
}

Support

Questions? Email team@bearforge.ai.