Base URL: http://localhost:8000 Version: 0.1.0

The PTC Agent API provides endpoints for interacting with the PTC (Plan-Think-Code) AI agent system. The agent executes code in isolated Daytona sandboxes and supports real-time streaming responses via Server-Sent Events (SSE).

This API is documented in two formats:

Open this folder (docs/api/) directly in Bruno to test API endpoints interactively.

Structure:

docs/api/ ├── opencollection.yml # Collection root ├── environments/ │ ├── development.yml # Local development (localhost:8000) │ └── production.yml # Production environment ├── 00-health/ # Health check ├── 10-chat/ # Chat streaming (SSE) ├── 20-workflow/ # Workflow control ├── 30-workspaces/ # Workspace CRUD ├── 35-workspace-files/ # File operations ├── 40-conversations/ # Conversation history ├── 50-users/ # User management ├── 55-portfolio/ # Portfolio holdings ├── 60-watchlist/ # Watchlist CRUD ├── 70-market-data/ # Market data endpoints └── 80-cache/ # Cache management 

Getting Started with Bruno:

1. Install Bruno
2. Open this folder as a collection
3. Select "development" environment
4. Create a workspace via 30-workspaces/create-workspace.yml
5. Test chat via 10-chat/stream-chat.yml

Detailed endpoint documentation with examples:

This section demonstrates the typical workflow for using the PTC Agent API.

Create a workspace with a dedicated Daytona sandbox. This provides an isolated environment for code execution.

curl -X POST "http://localhost:8000/api/v1/workspaces" \ -H "Content-Type: application/json" \ -H "X-User-Id: user-123" \ -d '{  "name": "My Project",  "description": "Development workspace for my project"  }'

Response:

{ "workspace_id": "ws-abc123-def456", "user_id": "user-123", "name": "My Project", "description": "Development workspace for my project", "sandbox_id": "sandbox-xyz789", "status": "running", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }

Use the workspace to run agent tasks via the streaming chat endpoint. The agent will execute code in the workspace's sandbox.

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \ -H "Content-Type: application/json" \ -d '{  "user_id": "user-123",  "workspace_id": "ws-abc123-def456",  "messages": [  {  "role": "user",  "content": "Create a Python script that prints Hello World"  }  ]  }'

SSE Response Stream:

event: message_chunk data: {"content": "I'll create a simple Python script", "agent": "assistant"} event: tool_calls data: {"tool_name": "write_file", "arguments": {"path": "/workspace/hello.py", "content": "print('Hello World')"}, "tool_call_id": "call_001"} event: artifact data: {"artifact_type": "file_operation", "artifact_id": "call_001", "agent": "ptc", "status": "completed", "payload": {"operation": "write_file", "file_path": "/workspace/hello.py", "line_count": 1}} event: tool_call_result data: {"tool_name": "write_file", "result": "File created successfully", "tool_call_id": "call_001"} event: done data: {"status": "completed", "thread_id": "thread-xyz"} 

Note: The response includes a thread_id which you'll need to reconnect if disconnected.

If your connection drops, you can reconnect to a running or completed workflow using the thread ID:

curl -N "http://localhost:8000/api/v1/chat/stream/thread-xyz/reconnect"

To avoid duplicate events, pass the last event ID you received:

curl -N "http://localhost:8000/api/v1/chat/stream/thread-xyz/reconnect?last_event_id=42"

The reconnect endpoint will:

1. Replay buffered events you may have missed
2. Continue streaming live events if the workflow is still running

Check the status of a workflow at any time:

curl "http://localhost:8000/api/v1/workflow/thread-xyz/status"

Response:

{ "thread_id": "thread-xyz", "status": "completed", "workspace_id": "ws-abc123-def456", "sandbox_id": "sandbox-xyz789", "started_at": "2025-01-15T10:30:00Z", "completed_at": "2025-01-15T10:30:45Z" }

Send follow-up messages using the same workspace_id:

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \ -H "Content-Type: application/json" \ -d '{  "user_id": "user-123",  "workspace_id": "ws-abc123-def456",  "messages": [  {  "role": "user",  "content": "Now run the script and show me the output"  }  ]  }'

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Create │ │ Chat Stream │ │ Reconnect │ │ Workspace │────▶ │ (with workspace) │────▶│ (if needed) │ │ POST /workspaces│ │ POST /chat/stream│ │ GET /reconnect │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Continue Chat │ │ (same workspace)│ │ POST /chat/stream│ └──────────────────┘ 

To display and continue from a past conversation, follow this workflow:

Fetch the user's conversation history to get available thread_id and workspace_id values:

curl "http://localhost:8000/api/v1/conversations?limit=50" \ -H "X-User-Id: user-123"

Response:

{ "threads": [ { "thread_id": "thread-abc123", "workspace_id": "ws-xyz789", "first_query_content": "Create a Python script...", "current_status": "completed", "updated_at": "2025-01-15T10:35:00Z" } ], "total": 15, "limit": 50, "offset": 0 }

Use the replay endpoint to stream the full conversation history as SSE events:

curl -N "http://localhost:8000/api/v1/threads/thread-abc123/replay"

This streams all messages, tool calls, and results exactly as they occurred, allowing the UI to reconstruct the conversation display.

Once replay is complete, send new messages using the same thread_id and workspace_id:

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \ -H "Content-Type: application/json" \ -d '{  "user_id": "user-123",  "workspace_id": "ws-xyz789",  "thread_id": "thread-abc123",  "messages": [  {  "role": "user",  "content": "Now add error handling to that script"  }  ]  }'

The agent will have full context from the previous conversation and can continue the work.

┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ List Conversations │ │ Replay Thread │ │ Continue Chat │ │ GET /conversations │────▶│ GET /threads/ │────▶│ POST /chat/stream │ │ (get thread_id, │ │ {thread_id}/replay │ │ (same thread_id & │ │ workspace_id) │ │ (display history) │ │ workspace_id) │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ 

See Conversations API for detailed endpoint documentation.

Currently, user identification is handled via:

• user_id field in request bodies (for chat endpoints)
• X-User-Id header (for workspace endpoints)

{ "status": "success", "data": { ... } }

{ "detail": "Error message describing what went wrong" }

{ "items": [...], "total": 100, "limit": 20, "offset": 0 }

The streaming endpoints emit Server-Sent Events. See Chat API - SSE Events for the complete list of event types.

See Models Reference for all request/response schemas including:

• ChatRequest / StatusResponse
• WorkspaceCreate / WorkspaceResponse
• WorkspaceThreadListItem / ThreadMessagesResponse

No rate limits are currently enforced. This may change in production deployments.

All API endpoints are versioned with the /api/v1/ prefix. Breaking changes will be introduced in new versions (e.g., /api/v2/).