Brain Gateway — API Reference

Overview

Base URL: https://your-domain.com

All endpoints accept Content-Type: application/json unless noted (STT uses multipart/form-data).

Authentication

Every request must include appId (your app slug) and appSecret (generated in the admin dashboard under Apps → Your App → Settings). API keys for AI providers are stored in the database vault — you do not pass provider keys in requests.

POST /api/brain/execute

Accepts two request shapes — both produce the same response.

// Standard request
fetch('https://your-domain.com/api/brain/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId:          'my-app',          // App slug from admin dashboard
    appSecret:      'sk-...',          // App secret from admin dashboard
    taskType:       'chat',            // Capability: chat | code | image | tts | stt | research | …
    message:        'Hello world',     // User message (max 32 000 chars)
    externalUserId: 'user-123',        // Optional — links memory to a user
    metadata:       { lang: 'en' },    // Optional key/value context
  }),
})

Or use the executeTask() interface with snake_case field names:

// executeTask() interface
fetch('https://your-domain.com/api/brain/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    app_id:      'my-app',
    app_secret:  'sk-...',
    mode:        'chat',               // Equivalent to taskType
    task:        'Hello world',        // Equivalent to message
    user_context: {                    // Merged into metadata.user_context
      name:     'Alice',
      language: 'en',
    },
  }),
})

Response

// Successful response
{
  "success":       true,
  "executed":      true,
  "traceId":       "abc-123",
  "taskType":      "chat",
  "output":        "Hello! How can I help you today?",
  "routedProvider": "openai",
  "routedModel":   "gpt-4o",
  "executionMode": "direct",
  "confidenceScore": 0.97,
  "validationUsed": false,
  "consensusUsed":  false,
  "fallbackUsed":   false,
  "safetyFlags":    [],
  "warnings":       [],
  "latencyMs":      342,
  "timestamp":      "2026-04-06T17:00:00.000Z"
}

POST /api/brain/stream

Returns Server-Sent Events (SSE). Supported for chat code reasoning task types.

// SSE streaming (text capabilities only)
const res = await fetch('https://your-domain.com/api/brain/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ appId, appSecret, taskType: 'chat', message }),
})
const reader = res.body.getReader()
const decoder = new TextDecoder()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  const chunk = decoder.decode(value)
  // Each line: "data: {"choices":[{"delta":{"content":"token"}}]}"
  // Final line: "data: [DONE]"
}

POST /api/brain/tts

// Text-to-Speech
fetch('https://your-domain.com/api/brain/tts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId, appSecret,
    text:     'Hello world',
    voice:    'nova',           // Optional voice ID
    gender:   'female',        // 'male' | 'female'
    accent:   'american',      // Optional accent hint
    provider: 'openai',        // Optional provider override
  }),
})
// Response: { audioUrl: 'https://…/audio.mp3', provider: 'openai', … }

POST /api/brain/stt

// Speech-to-Text (multipart/form-data)
const form = new FormData()
form.append('audio', audioFile)          // Audio file (mp3/wav/ogg/flac)
form.append('appId', 'my-app')
form.append('appSecret', 'sk-...')
fetch('https://your-domain.com/api/brain/stt', {
  method: 'POST',
  body: form,
})
// Response: { transcript: '…', provider: 'openai', … }

POST /api/brain/research

// Web research with sources
fetch('https://your-domain.com/api/brain/research', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId, appSecret,
    query: 'Latest AI breakthroughs 2026',
    depth: 'deep',   // 'shallow' | 'deep'
  }),
})
// Response: { answer: '…', sources: ['https://…', …], reasoning: ['…'] }

POST /api/brain/suggestive-image

// Image generation
fetch('https://your-domain.com/api/brain/suggestive-image', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId, appSecret,
    prompt:   'A serene mountain lake at dawn',
    style:    'photorealistic',  // Optional
    size:     '1024x1024',       // Optional
    provider: 'openai',          // Optional
  }),
})
// Response: { imageUrl: 'https://…', provider: 'openai', … }

Task Types

Error Handling

All error responses follow the same shape:

{
  "success": false,
  "executed": false,
  "traceId": "abc-123",
  "taskType": "chat",
  "output": null,
  "error": "Human-readable error message",
  "safetyFlags": [],           // Non-empty if content was blocked
  "warnings": [],
  "latencyMs": 12
}

Rate Limits

Default rate limits (configurable per-app in admin dashboard):

• 100 requests / minute per app
• 10 000 requests / day per app
• Token budgets configurable in Admin → Apps → Budget
• Responses include X-RateLimit-Remaining header