Execution & Streaming

Base URL http://localhost:3333/api/ · Authentication · Conventions

Execution Routes

Base path: /api/executions

Get All Executions

GET /

• Authentication: Required
• Description: Retrieve all executions for the authenticated user
• Response:

[
  {
    "id": "execution-id",
    "type": "agent|workflow|tool",
    "status": "running|completed|failed",
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-01-01T00:05:00Z",
    "metadata": {}
  }
]

Get Agent Activity Data

POST /activity

• Authentication: Required
• Body:

{
  "agentId": "agent-id",
  "timeRange": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-02T00:00:00Z"
  }
}

• Response:

{
  "activities": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "type": "chat|execution",
      "details": {}
    }
  ],
  "summary": {
    "totalChats": 10,
    "totalExecutions": 5
  }
}

Get Execution Details

GET /:id

• Authentication: Required
• Parameters:
  • id (path): Execution ID
• Description: Retrieve detailed information about a specific execution
• Response:

{
  "id": "execution-id",
  "type": "agent|workflow|tool",
  "status": "running|completed|failed",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-01T00:05:00Z",
  "input": {},
  "output": {},
  "logs": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "level": "info|error|debug",
      "message": "Log message"
    }
  ],
  "metadata": {}
}

Get Agent Executions

GET /agents/list

• Authentication: Required
• Description: Get all agent/orchestrator execution traces
• Response:

{
  "success": true,
  "runs": [
    {
      "id": "run-id",
      "agentId": "agent-id",
      "agentName": "Agent Name",
      "status": "completed|running|failed",
      "startedAt": "2024-01-01T00:00:00Z",
      "completedAt": "2024-01-01T00:05:00Z",
      "tokensUsed": 1500,
      "cost": 0.003
    }
  ]
}

Get Agent Execution Details

GET /agents/:id

• Authentication: Required
• Parameters:
  • id (path): Execution/run ID
• Description: Get detailed agent execution trace including messages and tool calls
• Response:

{
  "success": true,
  "run": {
    "id": "run-id",
    "agentId": "agent-id",
    "status": "completed",
    "messages": [],
    "toolCalls": [],
    "tokensUsed": 1500,
    "cost": 0.003,
    "startedAt": "2024-01-01T00:00:00Z",
    "completedAt": "2024-01-01T00:05:00Z"
  }
}

Delete Agent Execution

DELETE /agents/:id

• Authentication: Required
• Parameters:
  • id (path): Execution/run ID
• Description: Delete a specific agent execution trace
• Response:

{
  "success": true,
  "message": "Agent execution deleted"
}

Clear Completed Agent Executions

POST /agents/clear-completed

• Authentication: Required
• Description: Clear all completed agent execution traces for the authenticated user
• Response:

{
  "success": true,
  "cleared": 15
}

---

Get Conversation Summary

GET /conversation/:conversationId/summary

• Authentication: Required
• Description: Per-conversation monitoring summary — aggregates tokens, cache usage, and cost across all executions in the conversation
• Response: Aggregate totals object for the conversation

---

Stream Routes

Base path: /api/stream

Health Check

GET /health

• Authentication: None
• Description: Check if the stream service is running
• Response:

{
  "status": "OK"
}

Start Tool Forge Stream

POST /start-tool-forge-stream

• Authentication: Required
• Content-Type: multipart/form-data
• Body:
  • prompt (string): Tool generation prompt
  • files (file[]): Optional file attachments
• Response: Server-sent events stream

Cancel Tool Forge Stream

POST /cancel-tool-forge-stream

• Authentication: Required
• Body:

{
  "streamId": "stream-id"
}

• Response:

{
  "success": true,
  "message": "Stream cancelled"
}

Start Chat Stream

POST /start-chat-stream

• Authentication: Required
• Content-Type: multipart/form-data
• Body:
  • message (string): Chat message
  • files (file[]): Optional file attachments
• Response: Server-sent events stream

Cancel Chat Stream

POST /cancel-chat-stream

• Authentication: Required
• Body:

{
  "streamId": "stream-id"
}

• Response:

{
  "success": true,
  "message": "Stream cancelled"
}

Generate Tool

POST /generate-tool

• Authentication: Required
• Body:

{
  "description": "Tool description",
  "provider": "openai",
  "model": "gpt-4"
}

• Response:

{
  "success": true,
  "tool": {
    "name": "Generated Tool",
    "description": "Tool description",
    "config": {}
  }
}

Generate Workflow

POST /generate-workflow

• Authentication: Required
• Body:

{
  "description": "Workflow description",
  "provider": "openai",
  "model": "gpt-4"
}

• Response:

{
  "success": true,
  "workflow": {
    "name": "Generated Workflow",
    "description": "Workflow description",
    "nodes": [],
    "edges": []
  }
}

Generate Agent

POST /generate-agent

• Authentication: Required
• Body:

{
  "description": "Agent description",
  "provider": "openai",
  "model": "gpt-4"
}

• Response:

{
  "success": true,
  "agent": {
    "name": "Generated Agent",
    "description": "Agent description",
    "config": {}
  }
}

---

Speech Routes

Base path: /api/speech

Transcribe Audio

POST /transcribe

• Authentication: Required
• Content-Type: multipart/form-data
• Body:
  • audio (file): Audio file to transcribe (max 10MB)
• Description: Transcribe audio file to text using Whisper
• Response:

{
  "success": true,
  "transcript": "Transcribed text from audio"
}

Get Speech Service Status

GET /status

• Authentication: None
• Description: Get Whisper service status
• Response:

{
  "success": true,
  "status": "ready|loading|error",
  "model": "whisper-1",
  "initialized": true
}

Initialize Speech Service

POST /initialize

• Authentication: Required
• Description: Initialize Whisper service (download model if needed)
• Response:

{
  "success": true,
  "message": "Whisper service initialized successfully"
}

---