API Reference

Interactive endpoint docs backed by live responses. Run requests below to inspect current capability schema and deterministic output behavior.

Base URL

https://brainstackstudio.com

GET

/api/capability

Capability schema and allowed options.

POST

/api/capability

Deterministic explorer output for context inputs.

GET

/api/tools

Tool catalog for calculators and generators.

POST

/api/tools/[id]/execute

Execute a specific tool with inputs.

GET/api/capability

Returns the full capability schema including all valid industries, roles, and pain points that can be used as inputs to the explorer. Use this to populate selection interfaces or validate inputs before calling the POST endpoint.

Parameters

None required.

Example Request

bash

curl https://brainstackstudio.com/api/capability

Example Response

json

{
  "status": "ok",
  "deterministic": true,
  "confidenceThreshold": 0.65,
  "industries": [
    {
      "id": "operations",
      "label": "Operations / Business Management",
      "description": "Cross-functional ops, reporting, and process reliability."
    },
    {
      "id": "construction",
      "label": "Construction / Trades",
      "description": "Field coordination, estimating, and schedule accuracy."
    },
    {
      "id": "saas",
      "label": "SaaS Operations",
      "description": "Customer health, incidents, and retention risk."
    }
  ],
  "roles": [
    {
      "id": "owner",
      "label": "Owner / Exec"
    },
    {
      "id": "ops-manager",
      "label": "Ops Manager"
    },
    {
      "id": "engineer",
      "label": "Engineer"
    },
    {
      "id": "analyst",
      "label": "Analyst"
    }
  ],
  "painPoints": [
    {
      "id": "money",
      "label": "Money / Margin"
    },
    {
      "id": "labor",
      "label": "Labor / Staffing"
    },
    {
      "id": "process",
      "label": "Process Chaos"
    },
    {
      "id": "compliance",
      "label": "Compliance Risk"
    },
    {
      "id": "scale",
      "label": "Scale / Throughput"
    },
    {
      "id": "visibility",
      "label": "Visibility / Reporting"
    }
  ],
  "provenance": {
    "mode": "deterministic",
    "source": "registry",
    "stable": true,
    "registryVersion": "1.0.0"
  }
}

Response Fields

Field	Type	Description
status	string	"ok" on success
deterministic	boolean	Whether the explorer produces stable, repeatable output
confidenceThreshold	number	Minimum confidence score (0-1) for high-quality results
industries	array	Valid industry options with id, label, description
roles	array	Valid role options with id and label
painPoints	array	Valid pain point options with id and label
provenance	object	Metadata about how the response was generated

POST/api/capability

Runs a deterministic capability mapping for the given industry, role, and pain point combination. Returns a structured result with workflow steps, automation logic, value metrics, boundaries, and a decision trail. Same inputs always produce the same output.

Request Body Parameters

Parameter	Type	Required	Description
industry	string	Yes	Industry ID from GET /api/capability
role	string	Yes	Role ID from GET /api/capability
painPoint	string	Yes	Pain point ID from GET /api/capability

Example Request

bash

curl -X POST https://brainstackstudio.com/api/capability \
  -H "Content-Type: application/json" \
  -d '{"industry": "operations", "role": "ops-manager", "painPoint": "money"}'

Example Response

json

{
  "status": "ok",
  "confidenceThreshold": 0.65,
  "input": {
    "industry": "operations",
    "role": "ops-manager",
    "painPoint": "money"
  },
  "result": {
    "confidence": 0.82,
    "confidenceLabel": "High",
    "identifiedPain": "Margin leakage from inconsistent workflow execution and delayed approvals.",
    "workflow": [
      "Collect weekly revenue + cost signals from core systems",
      "Flag variance beyond tolerance thresholds",
      "Route approvals with time-boxed escalation"
    ],
    "automationLogic": [
      "If variance > 8% then open escalation task",
      "Auto-attach supporting context and owner",
      "Send summary to finance + ops leadership"
    ],
    "outputs": [
      "Variance report (weekly)",
      "Approval queue summary",
      "Margin-at-risk alert"
    ],
    "value": {
      "timeSaved": "6-10 hrs/week",
      "laborReduced": "1.0 FTE reporting load",
      "errorsPrevented": "7-12% fewer approval misses",
      "decisionLatency": "48h → 6h"
    },
    "boundaries": [
      "No internal systems or proprietary logic exposed.",
      "Outputs are deterministic and bounded to the selected context.",
      "If confidence is low, the system will ask for more detail."
    ],
    "decisionTrail": [
      "Industry operations matched to INDUSTRY_MAP entry.",
      "Pain point money resolved to margin-leakage mapping.",
      "Role ops-manager applied role weight 1.0.",
      "Final confidence 0.82 exceeds threshold 0.65."
    ],
    "provenance": {
      "mode": "deterministic",
      "source": "registry",
      "stable": true,
      "registryVersion": "1.0.0"
    }
  }
}

Error Responses

400Missing required fields or invalid input values.

422Unable to generate deterministic output for the given combination.

429Rate limit exceeded. Retry after the indicated period.

GET/api/tools

Returns a list of available tools including calculators, analyzers, generators, and visualizers. Filter by category or featured status using query parameters.

Query Parameters

Parameter	Type	Required	Description
category	string	No	Filter by category: calculators, analyzers, generators, visualizers
featured	string	No	Set to "true" to return only featured tools

Example Request

bash

curl "https://brainstackstudio.com/api/tools?featured=true"

Example Response

json

{
  "success": true,
  "count": 2,
  "tools": [
    {
      "id": "roi-calculator",
      "slug": "roi-calculator",
      "name": "AI Automation ROI Calculator",
      "shortDescription": "Calculate the return on investment for AI-driven workflow automation.",
      "category": "calculators",
      "industries": [
        "operations",
        "finance",
        "saas"
      ],
      "painPoints": [
        "money",
        "labor"
      ],
      "icon": "Calculator",
      "color": "cyan",
      "featured": true,
      "comingSoon": false
    },
    {
      "id": "process-audit",
      "slug": "process-audit",
      "name": "Process Audit Generator",
      "shortDescription": "Generate a structured audit of your operational workflows.",
      "category": "generators",
      "industries": [
        "operations",
        "manufacturing"
      ],
      "painPoints": [
        "process",
        "compliance"
      ],
      "icon": "ClipboardCheck",
      "color": "violet",
      "featured": true,
      "comingSoon": false
    }
  ]
}

POST/api/tools/[id]/execute

Execute a specific tool by its ID with the required input parameters. Each tool defines its own input schema. Use GET /api/tools to discover available tools and their IDs. Authenticated users get results persisted to their dashboard.

URL Parameters

Parameter	Type	Required	Description
id	string	Yes	Tool ID (alphanumeric, hyphens, underscores, max 50 chars)

Request Body

Field	Type	Required	Description
inputs	object	Yes	Key-value pairs matching the tool's input schema. Values can be strings or numbers.

Example Request

bash

curl -X POST https://brainstackstudio.com/api/tools/roi-calculator/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bss_your_api_key" \
  -d '{"inputs": {"monthlyVolume": 5000, "avgHandlingMinutes": 12, "hourlyLaborCost": 45, "errorRate": 4.5}}'

Example Response

json

{
  "success": true,
  "toolId": "roi-calculator",
  "toolName": "AI Automation ROI Calculator",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": {
    "confidence": 0.88,
    "summary": "Estimated annual savings of $127,800 with 14-month payback period.",
    "metrics": {
      "annualLaborSavings": 95400,
      "annualErrorReduction": 32400,
      "totalAnnualBenefit": 127800,
      "paybackMonths": 14
    }
  }
}

Error Responses

400Invalid tool ID format, missing required inputs, or tool is coming soon.

404Tool not found.

429Rate limit exceeded.

500Tool execution failed.

Rate Limits

Public endpoints use IP-based rate limits. Authenticated Pro API key calls use a shared key-bound bucket with higher throughput and usage telemetry. When a rate limit is exceeded, the response includes rate-limit headers so callers can back off cleanly.

Endpoint	Tier	Limit
GET /api/capability	Free	No limit
POST /api/capability	Free	100 requests/min per IP
GET /api/tools	Free	100 requests/min per IP
POST /api/tools/[id]/execute	Free / Pro API key	30 requests/min per IP or 100 requests/min per Pro API key

Interactive Capability Runner

Industry

Role

Pain point

cURL Example

bash

curl -X POST https://brainstackstudio.com/api/capability \
  -H "Content-Type: application/json" \
  -d '{"industry":"","role":"","painPoint":""}'

GET /api/capability Response

json

{
  "info": "Run GET request to view response"
}

POST /api/capability Response

json

{
  "info": "Run POST request to view response"
}

GET /api/tools Response

json

{
  "info": "Run tools request to view response"
}

Authentication

Pro users can generate API keys from the Dashboard. Pass your key via the X-API-Key header.