-
Notifications
You must be signed in to change notification settings - Fork 2
REST API
OCC exposes a REST API on port 4242 (configurable via REST_PORT). All responses are JSON unless noted.
Base URL: http://localhost:4242
GET /chains
Response:
[
{
"name": "deep-researcher",
"description": "Multi-perspective research engine",
"version": "1.0",
"stepCount": 6
}
]GET /chains/:name
Response: Raw YAML (Content-Type: text/yaml)
Errors: 404 if chain not found
POST /chains/:name
Content-Type: application/json (JSON object)
Content-Type: text/yaml (raw YAML string)
Response: {"ok": true}
Errors: 400 if YAML is invalid
DELETE /chains/:name
Response: {"ok": true}
Errors: 404 if chain not found
POST /execute/:name
Content-Type: application/json
{
"input": {
"topic": "quantum computing",
"depth": "deep"
}
}
Response: Returns immediately (async execution)
{"executionId": "1a2b3c4d5e6f7890"}Errors:
-
400— Chain not found or missing required inputs -
429— Too many concurrent executions (max 5)
GET /executions/:id/stream
Response: Server-Sent Events stream
data: {"type":"execution_started","executionId":"...","chainName":"deep-researcher"}
data: {"type":"step_started","executionId":"...","stepId":"search_mainstream","label":"Mainstream perspective"}
data: {"type":"step_output","executionId":"...","stepId":"search_mainstream","chunk":"Results found..."}
data: {"type":"step_done","executionId":"...","stepId":"search_mainstream","durationMs":12345}
data: {"type":"execution_done","executionId":"...","result":"Final output...","durationMs":47000}
Event types:
| Type | Fields | Description |
|---|---|---|
execution_started |
executionId, chainName | Chain execution began |
step_started |
executionId, stepId, label | Step began executing |
step_output |
executionId, stepId, chunk | Streaming output chunk |
step_done |
executionId, stepId, durationMs, inputTokens, outputTokens | Step completed |
step_error |
executionId, stepId, error | Step failed |
step_log |
executionId, stepId, message, level | Informational log |
step_cache_hit |
executionId, stepId | Step served from cache |
step_waiting_approval |
executionId, stepId, prompt | Gate step waiting |
gate_action |
executionId, stepId, action, reason | Gate approved/rejected |
execution_done |
executionId, result, durationMs | Chain completed |
execution_error |
executionId, error | Chain failed |
Notes:
- Heartbeat comment (
: heartbeat) sent every 30s to keep connection alive - Late-connecting clients receive catch-up events for completed steps
- Completed/failed executions send final event immediately then close
GET /executions/:id
Response:
{
"id": "1a2b3c4d5e6f7890",
"chainName": "deep-researcher",
"status": "done",
"input": {"topic": "quantum computing"},
"steps": {
"search_mainstream": {
"stepId": "search_mainstream",
"status": "done",
"output": "Research results...",
"durationMs": 12345,
"inputTokens": 500,
"outputTokens": 2000
}
},
"result": "Final synthesized report...",
"startedAt": "2026年03月29日T14:00:00.000Z",
"finishedAt": "2026年03月29日T14:00:47.000Z",
"durationMs": 47000
}Statuses: pending, running, done, error, skipped
GET /executions?limit=50&offset=0
Response: Array of execution summaries (without full step outputs).
DELETE /executions/:id
Kills all running processes for the execution. Steps are marked as skipped.
Response: {"ok": true}
POST /executions/:id/resume
Resumes a failed execution from the last checkpoint. Completed steps are skipped.
Response: {"executionId": "...", "result": "..."}
GET /approvals
Response:
[
{
"executionId": "1a2b3c4d",
"stepId": "approval_gate",
"chainName": "code-review",
"prompt": "Review the report before publishing",
"startedAt": "2026年03月29日T14:00:00.000Z"
}
]POST /executions/:id/approve/:stepId
Content-Type: application/json
{"approved": true}
Response: {"ok": true}
GET /schedules
GET /schedules/:id
POST /schedules
Content-Type: application/json
{
"label": "Daily briefing",
"chainName": "smart-briefing",
"input": {"topic": "tech news"},
"cron": "0 8 * * *",
"enabled": true
}
Response: 201 with schedule object
PUT /schedules/:id
Content-Type: application/json
{"cron": "0 9 * * *", "enabled": false}
PATCH /schedules/:id/toggle
Toggles enabled on/off.
POST /schedules/:id/run
Response: {"executionId": "..."}
DELETE /schedules/:id
GET /pipelines
GET /pipelines/:name
GET /pipelines/:name/json
POST /pipelines/:name
DELETE /pipelines/:name
POST /pipelines/:name/execute
Content-Type: application/json
{"input": {"topic": "AI agents"}}
Response: {"executionId": "..."}
GET /pipeline-executions
GET /pipeline-executions/:id
POST /generate-chain
Content-Type: application/json
{"description": "Create a chain that audits code for security vulnerabilities"}
Response (questions):
{
"status": "questions",
"sessionId": "gen-...",
"questions": ["What language?", "How deep?"]
}Response (created):
{
"status": "created",
"chainName": "security-audit",
"yaml": "name: security-audit\n..."
}POST /generate-chain/stream
Content-Type: application/json
{"description": "..."}
Returns SSE stream with real-time Claude output during chain generation.
GET /health
Response:
{"ok": true, "version": "2.0.0", "runningExecutions": 2}GET /download?path=/tmp/report.pdf
Serves a file as attachment. Restricted to /tmp and WORKSPACE_DIR.
Errors: 400 missing path, 403 path not allowed, 404 file not found
All origins allowed (*). Configure for production by modifying rest.ts.
Max 5 concurrent executions (configurable via MAX_CONCURRENT_EXECUTIONS env var). Returns 429 Too Many Requests when exceeded.