Skip to content

api-reference.md

Latest commit

 

History

History
259 lines (191 loc) · 4.08 KB

api-reference.md

File metadata and controls

259 lines (191 loc) · 4.08 KB
Raw

AgentFlow API Reference

Base URL: http://localhost:3001/api

Pipelines

List Pipelines

GET /pipelines

Returns all pipelines sorted by last updated.

Response 200

{
  "data": [Pipeline],
  "count": 2
}

Get Pipeline

GET /pipelines/:id

Response 200 — Pipeline object
Response 404 — { "error": "Pipeline not found" }

Create Pipeline

POST /pipelines

Body

{
  "name": "My Pipeline",           // required, max 100 chars
  "description": "...",            // optional, max 500 chars
  "nodes": [PipelineNode],         // optional, max 10 agents
  "edges": [PipelineEdge]          // optional
}

Node shape

{
  "id": "uuid",
  "type": "agent",
  "position": { "x": 100, "y": 200 },
  "data": {
    "id": "uuid",
    "name": "Researcher",
    "role": "researcher",          // researcher|analyzer|writer|critic|coordinator|coder|reviewer
    "systemPrompt": "You are...",
    "temperature": 0.7,            // 0.0–1.0
    "maxTokens": 2048              // 256–4096
  }
}

Response 201 — Created Pipeline
Response 400 — Validation error

Update Pipeline

PATCH /pipelines/:id

Partial update — omit fields to preserve them.

Response 200 — Updated Pipeline

Delete Pipeline

DELETE /pipelines/:id

Response 204 — No content

Executions

List Executions

GET /executions
GET /executions?pipelineId=<uuid>

Returns up to 100 most recent executions.

Get Execution

GET /executions/:id

Run Pipeline (Synchronous)

Waits for the full pipeline to complete before returning. Best for programmatic use.

POST /executions/run-sync

Body

{
  "pipelineId": "uuid",
  "input": "Research the latest AI breakthroughs"
}

Response 200 — Completed Execution object
Response 400 — Validation error
Response 404 — Pipeline not found
Response 500 — Execution failed

Stream Execution (SSE)

Subscribe to real-time events for a running execution.

GET /executions/:id/stream

Returns Content-Type: text/event-stream.
Connection closes automatically when execution completes.

Events

data: {"type":"execution_start","executionId":"...","timestamp":"..."}

data: {"type":"agent_start","executionId":"...","agentId":"...","agentName":"Researcher","timestamp":"..."}

data: {"type":"agent_token","executionId":"...","agentId":"...","token":"Hello","timestamp":"..."}

data: {"type":"agent_done","executionId":"...","agentId":"...","agentResult":{...},"timestamp":"..."}

data: {"type":"execution_done","executionId":"...","result":{...},"timestamp":"..."}

Dashboard Metrics

GET /executions/metrics

Response 200

{
  "totalRuns": 42,
  "successRate": 90.5,
  "avgTokensPerRun": 3250,
  "avgDurationMs": 8400,
  "recentExecutions": [Execution],
  "runsByDay": [
    { "date": "2025-03-15", "count": 5, "successCount": 4 }
  ]
}

Health

GET /health

{ "status": "ok", "timestamp": "2025-03-15T10:00:00.000Z" }

Error Format

All errors return:

{
  "error": "Human-readable message"
}

Validation errors include details:

{
  "error": "Validation failed",
  "details": [
    { "field": "name", "message": "name is required" }
  ]
}

Execution Object

{
  id: string
  pipelineId: string
  pipelineName: string
  status: "pending" | "running" | "completed" | "failed"
  input: string
  output: string                // Final output from terminal agents
  agents: [
    {
      agentId: string
      agentName: string
      role: AgentRole
      status: "idle" | "running" | "done" | "error"
      input: string
      output: string
      inputTokens: number
      outputTokens: number
      durationMs: number
      startedAt: string
      completedAt: string | null
      error: string | null
    }
  ]
  totalInputTokens: number
  totalOutputTokens: number
  durationMs: number
  startedAt: string
  completedAt: string | null
  error: string | null
}