FeaturesBenchmarksToolsMemoryAPIArchitectureDocs
Change language
Get Started
Developer API

HTTP API Reference

Full reference for the Parallel Research REST API. Manage sessions, stream events, and control AI research agents programmatically.

Overview

The Parallel Research API is a RESTful interface for managing AI research sessions. All responses are JSON-encoded. Streaming endpoints use Server-Sent Events (SSE).

Base URL
http://localhost:8080

The API supports two authentication methods via HTTP headers:

HTTP Headers
Authorization: Bearer <your-api-key>
X-Api-Key: <your-api-key>

Authentication

All API requests (except /health and /metrics) require a valid API key. Keys are configured via the PARALLEL_RESEARCH_API_KEYS environment variable as a comma-separated list.

Environment
PARALLEL_RESEARCH_API_KEYS=key-abc123,key-def456,key-ghi789

Each key maps to an independent identity. Rate limiting is applied per-key: 100 requests/minute for standard endpoints and 10 concurrent SSE connections. Exceeding limits returns 429 Too Many Requests.

⚠
Security note: Never expose API keys in client-side code or public repositories. Use environment variables or a secrets manager.

Endpoints

POST/api/v1/sessions

Create a new research session. The API spawns a coordinator agent that orchestrates sub-agents based on the query.

Request Body

JSONRequest
{
  "query": "Find SaaS companies in Berlin with 10-50 employees",
  "output_dir": "./results/session-001"
}
ParameterTypeDescription
querystringResearch query or task description
output_dirstringDirectory to store results (optional)

Response — 201 Created

JSONResponse
{
  "id": "sess_a1b2c3d4",
  "query": "Find SaaS companies in Berlin...",
  "status": "running",
  "created_at": "2026-08-07T10:30:00Z",
  "agents": [],
  "output_dir": "./results/session-001"
}
GET/api/v1/sessions

List all research sessions. Returns an array sorted by creation date (newest first).

Response — 200 OK

JSONResponse
[
  {
    "id": "sess_a1b2c3d4",
    "query": "Find SaaS companies in Berlin...",
    "status": "completed",
    "created_at": "2026-08-07T10:30:00Z"
  },
  {
    "id": "sess_e5f6g7h8",
    "query": "Analyze competitor pricing...",
    "status": "running",
    "created_at": "2026-08-07T11:00:00Z"
  }
]
GET/api/v1/sessions/:id

Retrieve detailed status of a specific session, including all spawned agents and their current states.

Path Parameters

ParameterTypeDescription
idstringSession identifier (e.g., sess_a1b2c3d4)

Response — 200 OK

JSONResponse
{
  "id": "sess_a1b2c3d4",
  "query": "Find SaaS companies in Berlin...",
  "status": "running",
  "created_at": "2026-08-07T10:30:00Z",
  "agents": [
    {
      "id": "agent_x1y2z3",
      "role": "web-researcher",
      "status": "running",
      "findings_count": 12
    },
    {
      "id": "agent_k4l5m6",
      "role": "data-analyst",
      "status": "idle"
    }
  ]
}
DELETE/api/v1/sessions/:id

Cancel a running session. All active agents are terminated gracefully.

Response — 200 OK

JSONResponse
{
  "success": true,
  "message": "Session sess_a1b2c3d4 cancelled"
}
POST/api/v1/sessions/:id/steer

Send a mid-run instruction to adjust the research direction without stopping the session.

Request Body

JSONRequest
{
  "instruction": "Focus only on companies with Series A funding"
}

Response — 200 OK

JSONResponse
{
  "success": true,
  "message": "Instruction delivered to session sess_a1b2c3d4"
}
GET/api/v1/sessions/:id/results

Retrieve completed research results for a session. Returns 404 if the session is still running.

Response — 200 OK

JSONResponse
{
  "session_id": "sess_a1b2c3d4",
  "status": "completed",
  "findings": [
    {
      "title": "TechCorp GmbH",
      "url": "https://techcorp.de",
      "summary": "B2B SaaS, 25 employees, Series A 2025",
      "confidence": 0.92
    }
  ],
  "output_files": [
    "./results/session-001/report.md",
    "./results/session-001/data.json"
  ]
}
GET/api/v1/sessions/:id/events

Open an SSE stream for real-time events from a specific session. Each event is a JSON object with event and data fields.

Response — 200 OK (text/event-stream)

SSEStream
event: AgentSpawned
data: {"agent_id":"agent_x1y2z3","role":"web-researcher"}

event: Finding
data: {"agent_id":"agent_x1y2z3","title":"TechCorp GmbH","confidence":0.92}

event: SessionCompleted
data: {"session_id":"sess_a1b2c3d4","duration_ms":45200}
GET/api/v1/events

Global SSE stream. Receives events from all active sessions. Useful for dashboards and monitoring.

Query Parameters

ParameterTypeDescription
typesstringComma-separated event types to filter (optional)
GET/api/v1/agents

List all active and recently completed agents across all sessions.

Response — 200 OK

JSONResponse
[
  {
    "id": "agent_x1y2z3",
    "session_id": "sess_a1b2c3d4",
    "role": "web-researcher",
    "status": "completed",
    "findings_count": 12
  }
]
GET/api/v1/agents/:id

Get detailed status and metadata for a specific agent, including tool calls and LLM interaction log.

Response — 200 OK

JSONResponse
{
  "id": "agent_x1y2z3",
  "session_id": "sess_a1b2c3d4",
  "role": "web-researcher",
  "status": "completed",
  "findings_count": 12,
  "tool_calls": 34,
  "llm_tokens_used": 18420,
  "started_at": "2026-08-07T10:30:01Z",
  "completed_at": "2026-08-07T10:30:42Z"
}
GET/health

Health check endpoint. No authentication required. Returns server status and version.

Response — 200 OK

JSONResponse
{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 86400
}
GET/metrics

Prometheus-compatible metrics endpoint. No authentication required. Scrape with any Prometheus-compatible collector.

Response — 200 OK (text/plain)

PrometheusMetrics
# HELP parallel_sessions_total Total number of sessions
# TYPE parallel_sessions_total counter
parallel_sessions_total 42

# HELP parallel_agents_active Currently active agents
# TYPE parallel_agents_active gauge
parallel_agents_active 3

# HELP parallel_request_duration_seconds Request latency
# TYPE parallel_request_duration_seconds histogram
parallel_request_duration_seconds_bucket{le="0.1"} 120

SSE Event Types

Server-Sent Events are pushed over persistent HTTP connections. Each event has a type name and a JSON-encoded data payload.

Event TypeDescription
SessionStartedFired when a new session is initialized
AgentSpawnedA new agent was created within the session
AgentStateChangedAgent transitioned between states (idle → running → completed)
FindingAn agent discovered a research finding
ToolCallStartedAgent began executing a tool (web search, scrape, etc.)
ToolCallCompletedTool execution finished with results
LlmStreamChunkStreaming token from the LLM response (for live UI)
AgentCompletedAgent finished its task successfully
AgentFailedAgent encountered an unrecoverable error
SessionCompletedAll agents finished; session results are ready
SessionFailedSession terminated due to a critical error

CLI Commands

The parallel CLI provides local development and operational tools. Install via cargo install parallel-research or build from source.

CommandDescription
parallel-research runExecute a one-shot research query and print results to stdout
parallel workerStart a background worker process for processing queued sessions
parallel-research tuiLaunch the interactive terminal UI for monitoring sessions
parallel-research serveStart the HTTP API server (this API)
parallel contactsManage contact lists for outreach campaigns
parallel resumeResume a previously interrupted session from checkpoint
parallel configView and manage configuration (API keys, model settings, etc.)

Error Codes

All error responses follow a consistent JSON format with a machine-readable code and a human-readable message.

JSONError Format
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
StatusCodeDescription
401unauthorizedMissing or invalid API key in request headers
404not_foundThe requested resource (session, agent) does not exist
429rate_limitedToo many requests — retry after the Retry-After header
500internal_errorUnexpected server error — check logs for details

Parallel Research API · Version 0.1.0 · GitHub