API Reference

Run BlackSpace agents from your own product using API keys and a single run endpoint.

Base URL

https://api.blackspace.ai

All endpoints in this guide are relative to this URL.

Authentication

Include your API key in a Bearer token header.

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Run an Agent

Run Agent Endpoint

POST

/api/v1/agents/{slug}/run

Starts a run for a specific agent and returns a run ID.

Request body

{
  "input": {
    "topic": "Q2 customer feedback",
    "notes": "Top complaints and feature requests"
  },
  "metadata": {
    "source": "dashboard"
  }
}

Response

{
  "run_id": "run_4f9131",
  "status": "queued",
  "agent_slug": "research-briefer"
}

Run status + stream

Poll run status

GET /api/v1/runs/{id}

{
  "run_id": "run_4f9131",
  "status": "completed",
  "output": "..."
}

Stream output with SSE

GET /api/v1/runs/{id}/stream

event: token
data: {"chunk":"First streamed chunk..."}

event: done
data: {"status":"completed"}

Code examples

curl

curl -X POST "https://api.blackspace.ai/api/v1/agents/research-briefer/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"topic":"Q2 feedback","notes":"..."}}'

Python

import requests

resp = requests.post(
  "https://api.blackspace.ai/api/v1/agents/research-briefer/run",
  headers={"Authorization": "Bearer " + API_KEY},
  json={"input": {"topic": "Q2 feedback", "notes": "..."}}
)
print(resp.json())

JavaScript

const res = await fetch("https://api.blackspace.ai/api/v1/agents/research-briefer/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.BLACKSPACE_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ input: { topic: "Q2 feedback", notes: "..." } })
});
console.log(await res.json());