API Reference

Complete documentation for the Soul-OS API. Integrate multi-agent cognitive capabilities into your applications.

Base URL

https://soul-os-frontend.harveytagalicud7.workers.dev

All API requests should be made to this base URL. For MindBridge direct access, use https://api.soul-os.cc

Authentication

Most endpoints require authentication via Bearer token in the Authorization header:

Authorization: Bearer dev-master-key

dev-master-key: Full access, 1000 RPM (development)

crs_*: Demo mode, 60 RPM (e.g., crs_test_key)

POST/api/chat

Create Chat Completion

🔒 Auth Required

Send a message and receive an AI response with memory, skill activation, and token tracking

Parameters

header

Authorization(string)required

Bearer token (dev-master-key or crs_* format)

Request Body

{
  "message": "What is the current architecture of Soul-OS?",
  "session_id": "session_abc123",
  "loadout_id": "default"
}

Response

{
  "response": "Soul-OS is a multi-agent cognitive ecosystem...",
  "session_id": "session_abc123",
  "tokens_used": 1247,
  "skills_activated": [
    "memory_search",
    "context_synthesis"
  ],
  "memory_retrieved": [
    {
      "id": "mem_001",
      "content": "MindBridge architecture...",
      "relevance": 0.92
    }
  ]
}

Notes

•Session IDs are auto-generated if not provided
•Loadout IDs: fast (Haiku), default (Sonnet), deep (Opus), code (Sonnet)
•Future: agent_id will route to specific agents (Architect, Builder, etc.)

POST/v1/chat/completions

OpenAI-Compatible Chat

Direct access to MindBridge router (OpenAI API format)

Request Body

{
  "model": "mindbridge:anthropic/claude-sonnet-4-6",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}

Response

{
  "id": "chatcmpl-xyz",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

Notes

•Bypasses Soul-OS cognitive stack
•No memory, skills, or session tracking
•Use for direct model access

Integration Examples

JavaScript / TypeScript

const response = await fetch(
  'https://soul-os-frontend.../api/chat',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer dev-master-key'
    },
    body: JSON.stringify({
      message: 'Hello, Soul-OS!',
      loadout_id: 'default'
    })
  }
);

const data = await response.json();
console.log(data.response);

Python

import requests

response = requests.post(
    'https://soul-os-frontend.../api/chat',
    headers={
        'Authorization': 'Bearer dev-master-key'
    },
    json={
        'message': 'Hello, Soul-OS!',
        'loadout_id': 'default'
    }
)

data = response.json()
print(data['response'])

cURL

curl -X POST \
  https://soul-os-frontend.../api/chat \
  -H 'Authorization: Bearer dev-master-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Hello, Soul-OS!",
    "loadout_id": "default"
  }'

OpenAI SDK (MindBridge)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.soul-os.cc/v1",
    api_key="not-required"
)

response = client.chat.completions.create(
    model="mindbridge:anthropic/claude-sonnet-4-6",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)