SMR API Surface
This reference is the control-plane route map used by scripts/smr_control.py.
Public project controls
POST /smr/projectsGET /smr/projectsGET /smr/projects/{project_id}PATCH /smr/projects/{project_id}GET /smr/projects/{project_id}/statusPOST /smr/projects/{project_id}/pausePOST /smr/projects/{project_id}/resumePOST /smr/projects/{project_id}/archivePOST /smr/projects/{project_id}/unarchivePOST /smr/projects/archive-oldest
Onboarding and provider keys
POST /smr/projects/{project_id}/onboarding/startPOST /smr/projects/{project_id}/onboarding/complete_stepPOST /smr/projects/{project_id}/onboarding/dry_runGET /smr/projects/{project_id}/onboarding/statusPOST /smr/projects/{project_id}/provider_keysGET /smr/projects/{project_id}/provider_keys/{provider}/{funding_source}/status
Starting data
POST /smr/projects/{project_id}/starting-data/upload-urls
Runs and human-in-the-loop surfaces
Canonical run routes (always available):
POST /smr/projects/{project_id}/triggerGET /smr/runs?project_id=...GET /smr/runs/{run_id}POST /smr/runs/{run_id}/pausePOST /smr/runs/{run_id}/resumePOST /smr/runs/{run_id}/stopGET /smr/runs/{run_id}/questionsPOST /smr/runs/{run_id}/questions/{question_id}/respondGET /smr/projects/{project_id}/questions?status_filter=...GET /smr/runs/{run_id}/approvalsGET /smr/projects/{project_id}/approvals?status_filter=...POST /smr/runs/{run_id}/approvals/{approval_id}/approvePOST /smr/runs/{run_id}/approvals/{approval_id}/denyGET /smr/runs/{run_id}/artifactsGET /smr/artifacts/{artifact_id}GET /smr/artifacts/{artifact_id}/content
Project-scoped run aliases (enforce project_id + org_id scoping):
GET /smr/projects/{project_id}/runsGET /smr/projects/{project_id}/runs/activeGET /smr/projects/{project_id}/runs/{run_id}POST /smr/projects/{project_id}/runs/{run_id}/pausePOST /smr/projects/{project_id}/runs/{run_id}/resumePOST /smr/projects/{project_id}/runs/{run_id}/stopGET /smr/projects/{project_id}/runs/{run_id}/questionsPOST /smr/projects/{project_id}/runs/{run_id}/questions/{question_id}/respondGET /smr/projects/{project_id}/runs/{run_id}/approvalsPOST /smr/projects/{project_id}/runs/{run_id}/approvals/{approval_id}/approvePOST /smr/projects/{project_id}/runs/{run_id}/approvals/{approval_id}/denyGET /smr/projects/{project_id}/runs/{run_id}/artifacts
Results, logs, and orchestrator status (run-scoped)
GET /smr/projects/{project_id}/runs/{run_id}/results— outcome + artifacts-by-type + log debug hintGET /smr/projects/{project_id}/runs/{run_id}/orchestrator— orchestrator phase, heartbeat, turn count, and full turn history (phase,started_at,finished_at,completed,error,duration_secondsper turn)GET /smr/projects/{project_id}/runs/{run_id}/logs— structured VictoriaLogs query (task_key, component, limit, start, end)GET /smr/projects/{project_id}/victoria-logs/search— free-text LogSQL search across a project
Ops and observability
GET /smr/projects/{project_id}/usageGET /smr/projects/{project_id}/ops_status
Runtime surfaces
- SDK client:
synth_ai.sdk.managed_research.SmrControlClient - CLI group:
synth-ai managed-research ... - MCP server:
synth-ai-mcp-managed-researchorsynth-ai managed-research mcp-server
Workspace git status
GET /smr/projects/{project_id}/workspace/git— read-only git status:configured,commit_sha,last_pushed_at,default_branch,vcs_provider,remote_repo. Storage internals (bucket, archive key) are intentionally omitted.
MCP tools (29 total)
| Tool | Description |
|---|---|
smr_list_projects |
List managed research projects |
smr_get_project |
Fetch a project by id |
smr_get_project_status |
Get project status |
smr_create_project |
Create a new project |
smr_pause_project |
Pause a project |
smr_resume_project |
Resume a paused project |
smr_archive_project |
Archive a project |
smr_unarchive_project |
Unarchive a project |
smr_get_starting_data_upload_urls |
Get presigned upload URLs for starting data |
smr_upload_starting_data |
Upload starting data files (text) |
smr_trigger_run |
Trigger a new run |
smr_list_runs |
List runs (all or active-only) |
smr_get_run |
Fetch a run by id |
smr_pause_run |
Pause a run |
smr_resume_run |
Resume a paused run |
smr_stop_run |
Stop a run |
smr_list_project_questions |
List project-level questions |
smr_respond_question |
Respond to a question |
smr_list_project_approvals |
List project-level approvals |
smr_resolve_approval |
Approve or deny an approval |
smr_get_usage |
Fetch project usage metrics |
smr_get_ops_status |
Fetch ops/task status |
smr_get_run_logs |
Query VictoriaLogs for a run (structured) |
smr_search_project_logs |
Free-text LogSQL search across a project |
smr_list_run_artifacts |
List run artifacts |
smr_get_artifact |
Fetch artifact metadata |
smr_get_run_results |
Run result summary: outcome, artifacts, log hint |
smr_get_project_git_status |
Read-only workspace git: commit SHA, last push, branch, remote repo |
smr_get_orchestrator_status |
Orchestrator phase, heartbeat, turn count, and full turn history |