API Reference

The Deep Research Assistant exposes a REST API (FastAPI) for creating, inspecting, and managing research runs.

Base URL

http://localhost:8080/v1

Endpoints

Research Runs

Create Research Run

POST /v1/research-runs

{
  "objective": {
    "title": "Secure agent runtime analysis",
    "primary_question": "Which architectural controls are required for a secure enterprise agent runtime?",
    "decision_to_support": "Define platform architecture"
  },
  "mode": "review_first",
  "constraints": {
    "minimum_primary_source_ratio": 0.6,
    "maximum_cost": 50
  }
}

Inspect Research Run

GET /v1/research-runs/{run_id}

Returns the full research run aggregate with all nested entities. Currently returns summary status, objective/scope, counts, and a report preview.

Get Research Graph

GET /v1/research-runs/{run_id}/graph

Returns the concept map projection: topics, questions, claims, and their relationships. Currently returns run metadata plus claims and sources. Use /concept-map for the projected topic graph.

Get Research Frontier

GET /v1/research-runs/{run_id}/frontier

Returns open, resolved, and blocked questions with priorities and dependency edges. Currently returns the current question list and priority map.

Get Progress

GET /v1/research-runs/{run_id}/progress

Returns current phase, budget consumption, and completion estimates.

Stream Events

GET /v1/research-runs/{run_id}/events

SSE stream of workflow events: run.started, perspective.created, claim.created, verification.passed, etc.

Interventions

Apply Intervention

POST /v1/research-runs/{run_id}/interventions

{
  "type": "challenge_claim",
  "target_id": "C-104",
  "instruction": "Find independent evidence that contradicts this claim."
}

Supported intervention types:

• add_question — add a new research question
• challenge_claim — trigger counter-evidence search
• add_topic / remove_topic — queue a scope change
• add_perspective — queue a new perspective
• change_budget — queue a budget change

Approvals

Get Pending Approvals

GET /v1/research-runs/{run_id}/approvals

Decide Approval

POST /v1/research-runs/{run_id}/approvals/{approval_id}

{
  "decision": "approved",
  "rationale": "Scope and risk assessment look correct"
}

Approval gates:

• Gate A — Scope: triggered for high-risk or ambiguous requests
• Gate B — Research Plan: perspectives, questions, budget
• Gate C — Evidence & Outline: claims, contradictions, proposed structure
• Gate D — Publication: required for external distribution

Export

POST /v1/research-runs/{run_id}/exports

{
  "format": "markdown"
}

Current implementation returns the generated report body and echoes the requested format. Dedicated HTML/JSON/evidence-package rendering is not implemented yet.

Response Model

Most endpoints currently return plain JSON objects rather than a shared response envelope.

{
  "run_id": "run-001",
  "status": "completed"
}

Events

The SSE event stream emits typed events at each workflow stage: