API Reference

All endpoints are served by the Purple8 gateway on port 8081 in development. Every authenticated request must include a valid Bearer token from /api/v1/auth/login.

Base URL: http://localhost:8081

Authentication

POST /api/v1/auth/login

Obtain a JWT access token.

// Request
{ "username": "user@example.com", "password": "s3cret" }

// Response
{ "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }

Endpoint	Method	Description
/api/v1/auth/login	POST	Obtain JWT
/api/v1/auth/me	GET	Current user profile and roles
/api/v1/auth/logout	POST	Invalidate token
/api/v1/auth/refresh	POST	Exchange near-expired token

---

Pipeline v2 (Recommended)

POST /pipeline/v2/stream

Start a build session. Returns text/event-stream.

{
  "prompt": "Build a FastAPI CRUD app with PostgreSQL and JWT auth",
  "goal": "prototype",
  "mode": "plus",
  "hitl_enabled": true,
  "hitl_phases": ["planning"],
  "project_name": "my-crud-api"
}

Field	Values
goal	prototype · mvp · production
mode	standard · plus

SSE events emitted:

event: phase_start
data: {"phase": "planning", "agents": ["IdeationAgent", "ArchitectureAgent"]}

event: agent_output
data: {"agent": "IdeationAgent", "content": "...", "tokens": 412}

event: checkpoint
data: {"checkpoint_id": "chk_a1b2c3", "phase": "planning", "type": "hitl"}

event: phase_complete
data: {"phase": "planning", "duration_s": 28.4}

event: build_complete
data: {"project_name": "my-crud-api", "files": 47, "lines": 3820, "ctq_score": 84}

Endpoint	Method	Description
/pipeline/v2/stream	POST	Start session (SSE)
/pipeline/v2/sessions	GET	List sessions
/pipeline/v2/session/{id}	GET	Session detail and outputs
/pipeline/v2/session/{id}	DELETE	Cancel or delete session
/pipeline/v2/checkpoint/{id}/resolve	POST	Resume HITL checkpoint

Checkpoint resolve body: { "action": "approve" | "reject" | "modify", "feedback": "..." }

---

BRD Generation

Endpoint	Method	Description
/api/brd/generate	POST	Generate a full BRD from a description
/api/brd/enhance	POST	Refine an existing BRD

// POST /api/brd/generate
{
  "project_name": "customer-portal",
  "description": "A self-service portal for customers to manage subscriptions",
  "include_sections": ["executive_summary", "functional_requirements", "data_model"]
}

---

IDE Copilot

Edit Mode

Endpoint	Method	Description
/api/ide/copilot/edit/complete	POST	Inline code completion at cursor
/api/ide/copilot/edit/action	POST	Named action (explain, refactor, add-tests)
/api/ide/copilot/edit/suggest	POST	Suggest improvements for selected code

Agent Mode

Endpoint	Method	Description
/api/ide/copilot/agent/chat	POST	Chat message + response
/api/ide/copilot/agent/chat/stream	POST	Streaming chat (SSE)

Quick Actions

Endpoint	Method	Description
/api/ide/copilot/quick/explain	POST	Explain selected code
/api/ide/copilot/quick/fix	POST	Suggest fix for an error

---

Sandbox

Endpoint	Method	Description
/api/sandbox/sessions	POST	Create sandbox session
/api/sandbox/sessions	GET	List active sessions
/api/sandbox/sessions/{id}	GET	Session status and logs
/api/sandbox/sessions/{id}	DELETE	Terminate session
/api/sandbox/sessions/{id}/launch	POST	Execute command in sandbox
/api/sandbox/sessions/from-project/{name}	GET	Get or create session for project

// POST /api/sandbox/sessions
{ "runtime": "python3.12", "project_name": "my-crud-api", "timeout_seconds": 300 }

// POST /api/sandbox/sessions/{id}/launch
{ "command": "pytest tests/ -v --tb=short", "cwd": "/workspace" }

runtime values: python3.12 · node20

---

Git Integration

Endpoint	Method	Description
/api/git/status	GET	Working tree status
/api/git/diff	GET	Unstaged changes
/api/git/stage	POST	Stage files
/api/git/commit	POST	Commit staged files
/api/git/quick-commit	POST	Stage all + commit in one call
/api/git/branch	GET	List branches
/api/git/push	POST	Push to remote

---

Promotion

Endpoint	Method	Description
/promotion/status	GET	Promotion status across environments
/promotion/check	POST	Validate project is ready to promote
/promotion/request	POST	Request promotion to next environment
/promotion/approve	POST	Approve request (admin / lead)
/promotion/reject	POST	Reject request with reason
/promotion/execute	POST	Execute approved promotion
/promotion/rollback	POST	Roll back most recent promotion
/promotion/environments	GET	All configured environments

---

Quality / CTQ

Endpoint	Method	Description
/quality/portfolio	GET	CTQ summary across all projects
/quality/project/{name}	GET	Full CTQ scorecard
/quality/ctq-scorecard	GET	Aggregate platform metrics
/quality/trends	GET	Historical CTQ data
/quality/refresh	POST	Trigger a fresh quality scan

---

Memory

Endpoint	Method	Description
/api/memory/memories	POST	Store a memory
/api/memory/memories	GET	List memories (?project=&tags=&limit=)
/api/memory/memories/{id}	DELETE	Delete a memory
/api/memory/memories/search	GET	Semantic search (?q=&project=)
/api/memory/memories/recent	GET	Recently accessed memories

---

Checkpoints

Endpoint	Method	Description
/api/checkpoints	GET	List checkpoints (?session_id=&status=)
/api/checkpoints/{id}	GET	Checkpoint detail
/api/checkpoints/resumable-tasks	GET	Sessions awaiting HITL input
/api/checkpoints/{id}	DELETE	Dismiss checkpoint

---

Observability

Endpoint	Method	Description
/api/observability/agents	GET	Per-agent execution metrics
/api/observability/system-metrics	GET	CPU, memory, container health
/api/observability/logs	GET	Structured log stream
/api/observability/traces	GET	Distributed traces per session
/api/observability/coverage	GET	Test coverage across all projects
/api/observability/run-tests	POST	Trigger test suite, stream results

---

Pipeline v1 (Legacy)

Endpoint	Method	Description
/pipeline/run	POST	Run full pipeline synchronously
/pipeline/ideate	POST	Run ideation phase only
/pipeline/ideate/approve	POST	Approve ideation, start implementation
/pipeline/register-prompt	POST	Save prompt to memory store