API reference

Base URL https://api.braincore.pro. Every endpoint is served by a single zero-dependency Node process. Requests accept an optional x-api-key header (issued after checkout); without a key the public demo tenant is used.

Endpoints

MethodPathPurposeAuth
GET/healthLiveness and node identity—
GET/statusNode stats + membership + live viewers—
GET/metricsCounters used by the landing page—
POST/taskSubmit work into the swarm (optional outputSchema)optional key
GET/tasksKnown tasks, results, CRDT snapshot—
POST/v1/fitnessEdge reports fitness (metrics only, HMAC)HMAC signature
GET/v1/genome/best?k=1Best genome from the top 10 %—
GET/v1/registry/statsGenome leaderboard and recent reports—
POST/v1/stripe/webhookStripe → issue API key after paymentStripe signature
GET/v1/keysList issued keys (masked)admin key
WS/eventsLive swarm feed (snapshot + events)—

Submit a task

curl -s https://api.braincore.pro/task \
  -H 'content-type: application/json' \
  -H "x-api-key: $BRAINCORE_API_KEY" \
  -d '{
    "type": "support.ticket",
    "payload": { "text": "Reset my password" },
    "value": 10,
    "ttl": 30000
  }'

type is required. value is the priority used to order claims; ttl is milliseconds before the task expires.

Add outputSchema and the answer is enforced: extra fields are dropped, prose is stripped, enum values are checked, and one corrective retry happens if the model drifts.

{
  "type": "support.ticket",
  "payload": { "text": "Reset my password" },
  "outputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["category", "priority"],
    "properties": {
      "category": { "enum": ["refund","billing","technical","ecommerce","sales","other"] },
      "priority": { "enum": ["low","normal","high"] }
    }
  }
}

Report fitness (edge → registry)

// only these eight fields are accepted
{
  "node_id": "edge-us-1",
  "genome_id": "genom-B",
  "fitness": 0.87,
  "tasks_done": 142,
  "pheromone_efficiency": 0.92,
  "tenant_hash": "…",
  "ts": 1770000000000,
  "sig": "<hmac-sha256 of the body>"
}

Extra fields, or any string longer than 128 characters, are rejected — that closes the obvious side channels.

Live feed (WebSocket)

const ws = new WebSocket('wss://live.braincore.pro/events')
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data)
  // { type: 'snapshot', nodes: [...], pheromones: [...], stats: {...} }
  // { type: 'event', kind: 'task_done', nodeId, ms }
}

Snapshots every second; events pushed immediately. The server implements RFC 6455 itself — no ws package.

Run your own swarm

export NMQ_CLUSTER_SECRET=$(openssl rand -hex 32)

node src/index.js --port=8001 --api-port=8081
node src/index.js --port=8002 --peers=127.0.0.1:8001
node src/index.js --port=8003 \
     --peers=127.0.0.1:8001,127.0.0.1:8002

# SYNCED in 0.0s, 3 nodes alive

UDP gossip runs on the same port number as the HTTP admin (different protocol namespaces). The API and live feed run on --api-port.

Environment variables

NameUsed forRequired
NMQ_CLUSTER_SECRETHMAC gossip signatures + AES-256-GCM payload keyyes
NMQ_REDIS_URLRedis for the RESP queue (optional)no
STRIPE_WEBHOOK_SECRETVerifying /v1/stripe/webhookfor billing
BRAINCORE_ADMIN_KEYAdmin access to /v1/keysfor admin

Secret values are never echoed by the API. Rotate NMQ_CLUSTER_SECRET during a maintenance window: all nodes must restart together.