API

OpenAI-compatible inference, agent invocation, and fleet management. Drop-in replacement for any OpenAI client library.

Health check. Returns gateway status, version, and uptime. No authentication required.

List all registered agents with their name, role, status, and capabilities.

Invoke a specific agent with a task. The gateway routes the request to the appropriate node and returns the result.

{
  "agent": "alice",
  "task": "deploy auth-worker to cloudflare"
}

curl -X POST https://api.blackroad.io/v1/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer br_your_api_key" \
  -d '{"agent": "alice", "task": "deploy auth-worker to cloudflare"}'

const res = await fetch("https://api.blackroad.io/v1/invoke", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer br_your_api_key"
  },
  body: JSON.stringify({
    agent: "alice",
    task: "deploy auth-worker to cloudflare"
  })
});
const data = await res.json();

OpenAI-compatible chat completions. Supports streaming. Drop-in replacement for any OpenAI client — just change the base URL.

{
  "model": "llama3",
  "messages": [
    {"role": "user", "content": "Explain sovereign infrastructure"}
  ],
  "stream": true
}

curl https://api.blackroad.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer br_your_api_key" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Explain sovereign infrastructure"}],
    "stream": true
  }'

const res = await fetch("https://api.blackroad.io/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer br_your_api_key"
  },
  body: JSON.stringify({
    model: "llama3",
    messages: [{ role: "user", content: "Explain sovereign infrastructure" }],
    stream: true
  })
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Authentication

API keys are passed in the Authorization header. Keys are tier-based — the tier determines rate limits and available providers.

Authorization: Bearer br_your_api_key

Rate Limits

Limits are enforced per API key. Exceeding the limit returns HTTP 429 with a Retry-After header.