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
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /health | Liveness and node identity | — |
| GET | /status | Node stats + membership + live viewers | — |
| GET | /metrics | Counters used by the landing page | — |
| POST | /task | Submit work into the swarm (optional outputSchema) | optional key |
| GET | /tasks | Known tasks, results, CRDT snapshot | — |
| POST | /v1/fitness | Edge reports fitness (metrics only, HMAC) | HMAC signature |
| GET | /v1/genome/best?k=1 | Best genome from the top 10 % | — |
| GET | /v1/registry/stats | Genome leaderboard and recent reports | — |
| POST | /v1/stripe/webhook | Stripe → issue API key after payment | Stripe signature |
| GET | /v1/keys | List issued keys (masked) | admin key |
| WS | /events | Live 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
| Name | Used for | Required |
|---|---|---|
| NMQ_CLUSTER_SECRET | HMAC gossip signatures + AES-256-GCM payload key | yes |
| NMQ_REDIS_URL | Redis for the RESP queue (optional) | no |
| STRIPE_WEBHOOK_SECRET | Verifying /v1/stripe/webhook | for billing |
| BRAINCORE_ADMIN_KEY | Admin access to /v1/keys | for admin |
Secret values are never echoed by the API. Rotate NMQ_CLUSTER_SECRET during a maintenance window: all nodes must restart together.