roboco/docs/architecture/api_overview.md

# API Overview

This document provides a high-level overview of the RoboCo API structure, organized by functional domain.

## API Architecture

The API is built with FastAPI and follows RESTful principles. All endpoints require agent authentication via headers:

```
X-Agent-ID: <uuid or slug>
X-Agent-Role: <role>
X-Agent-Team: <team>
```

## Route Modules

| Module | Path Prefix | Description |
|--------|-------------|-------------|
| `health` | `/health` | Health checks and readiness probes |
| `agents` | `/agents` | Agent lookup and information |
| `tasks` | `/tasks` | Task CRUD and lifecycle management |
| `projects` | `/projects` | Git project/repository management |
| `work_session` | `/work-sessions` | Work session tracking |
| `git` | `/git` | Git operations for agents |
| `channels` | `/channels` | Communication channels |
| `groups` | `/groups` | Channel groups |
| `sessions` | `/sessions` | Message sessions |
| `messages` | `/messages` | Message operations |
| `notifications` | `/notifications` | Formal notifications |
| `journals` | `/journals` | Agent journals |
| `optimal` | `/optimal` | Knowledge base and RAG |
| `kanban` | `/kanban` | Kanban board views |
| `dashboard` | `/dashboard` | Dashboard data |
| `orchestrator` | `/orchestrator` | Agent orchestration |
| `stream` | `/stream` | WebSocket streaming |
| `test` | `/test` | Test execution |
| `a2a` | `/a2a` | Agent-to-Agent protocol |

---

## Task API (`/tasks`)

Full CRUD operations and lifecycle management for tasks.

### CRUD Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/tasks` | Create a new task |
| `GET` | `/tasks` | List tasks with optional filters |
| `GET` | `/tasks/my` | Get tasks assigned to current agent |
| `GET` | `/tasks/pending` | Get pending tasks available to claim |
| `GET` | `/tasks/blocked` | Get blocked tasks |
| `GET` | `/tasks/awaiting-qa` | Get tasks awaiting QA review |
| `GET` | `/tasks/awaiting-docs` | Get tasks awaiting documentation |
| `GET` | `/tasks/awaiting-pm-review` | Get tasks awaiting PM review |
| `GET` | `/tasks/awaiting-ceo-approval` | Get CEO approval queue |
| `GET` | `/tasks/team/{team}` | Get tasks for a specific team |
| `GET` | `/tasks/stats` | Get task counts by status |
| `GET` | `/tasks/stats/by-team` | Get task counts by team |
| `GET` | `/tasks/{task_id}` | Get a specific task with full context |
| `PUT/PATCH` | `/tasks/{task_id}` | Update a task |
| `DELETE` | `/tasks/{task_id}` | Delete a task |
| `GET` | `/tasks/{task_id}/subtasks` | Get immediate subtasks |
| `GET` | `/tasks/{task_id}/descendants` | Get all descendants (recursive) |

### Lifecycle Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/tasks/{task_id}/claim` | Claim a pending task |
| `POST` | `/tasks/{task_id}/start` | Start working on claimed task |
| `POST` | `/tasks/{task_id}/block` | Block task on dependency |
| `POST` | `/tasks/{task_id}/soft-block` | Block on external factor |
| `POST` | `/tasks/{task_id}/unblock` | Unblock a task |
| `POST` | `/tasks/{task_id}/pause` | Pause active task |
| `POST` | `/tasks/{task_id}/resume` | Resume paused task |
| `POST` | `/tasks/{task_id}/verify` | Submit for self-verification |
| `POST` | `/tasks/{task_id}/submit-qa` | Submit to QA |
| `POST` | `/tasks/{task_id}/pass-qa` | QA passes task |
| `POST` | `/tasks/{task_id}/fail-qa` | QA fails task |
| `POST` | `/tasks/{task_id}/docs-complete` | Mark docs complete (documenter) |
| `POST` | `/tasks/{task_id}/submit-pm-review` | Submit for PM review |
| `POST` | `/tasks/{task_id}/complete` | Complete task (PM) |
| `POST` | `/tasks/{task_id}/cancel` | Cancel task (PM) |
| `POST` | `/tasks/{task_id}/activate` | Activate from backlog (PM) |

### CEO Approval Workflow

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/tasks/{task_id}/escalate-to-ceo` | Escalate to CEO (PM) |
| `POST` | `/tasks/{task_id}/ceo-approve` | CEO approves |
| `POST` | `/tasks/{task_id}/ceo-reject` | CEO rejects |

### Escalation & Substitution

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/tasks/{task_id}/escalate` | Escalate to PM/management (all agents) |
| `POST` | `/tasks/{task_id}/substitute` | Request substitution (assigned agent) |

### Progress & Artifacts

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/tasks/{task_id}/progress` | Add progress update |
| `POST` | `/tasks/{task_id}/checkpoint` | Add state checkpoint |
| `POST` | `/tasks/{task_id}/commit` | Link a commit |
| `GET` | `/tasks/{task_id}/sessions` | Get linked sessions |

---

## Agent API (`/agents`)

Agent lookup and information endpoints.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/agents` | List agents (filter by slug, role, team) |
| `GET` | `/agents/{agent_id}` | Get agent by ID or slug |

---

## Project API (`/projects`)

CRUD operations for managing git projects/repositories.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/projects` | List projects (filter by cell, active) |
| `POST` | `/projects` | Register a new project (PM) |
| `GET` | `/projects/{project_id}` | Get project details |
| `PUT/PATCH` | `/projects/{project_id}` | Update project |
| `DELETE` | `/projects/{project_id}` | Delete project |
| `POST` | `/projects/{project_id}/sync` | Update sync state |
| `POST` | `/projects/{project_id}/workspace` | Set workspace path |

---

## Git API (`/git`)

Git operations for agents working on code tasks.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/git/{project}/status` | Get git status |
| `GET` | `/git/{project}/diff` | Get diff |
| `GET` | `/git/{project}/log` | Get commit log |
| `GET` | `/git/{project}/branches` | List branches |
| `POST` | `/git/{project}/branch` | Create a branch |
| `POST` | `/git/{project}/checkout` | Checkout a branch |
| `POST` | `/git/{project}/commit` | Create a commit |
| `POST` | `/git/{project}/push` | Push changes |
| `POST` | `/git/{project}/pr` | Create a pull request |
| `POST` | `/git/{project}/pr/merge` | Merge a pull request |

---

## Work Session API (`/work-sessions`)

Work session tracking for git-enabled tasks.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/work-sessions` | List work sessions |
| `POST` | `/work-sessions` | Create a work session |
| `GET` | `/work-sessions/{id}` | Get work session details |
| `PATCH` | `/work-sessions/{id}` | Update work session |
| `GET` | `/work-sessions/task/{task_id}` | Get work session for task |
| `GET` | `/work-sessions/agent/{agent_id}` | Get agent's active session |

---

## Messaging API

### Channels (`/channels`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/channels` | List channels |
| `POST` | `/channels` | Create a channel |
| `GET` | `/channels/{slug}` | Get channel by slug |
| `PUT` | `/channels/{slug}` | Update channel |
| `DELETE` | `/channels/{slug}` | Delete channel |

### Groups (`/groups`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/groups` | List groups |
| `POST` | `/groups` | Create a group |
| `GET` | `/groups/{id}` | Get group |
| `PUT` | `/groups/{id}` | Update group |
| `DELETE` | `/groups/{id}` | Delete group |

### Sessions (`/sessions`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/sessions` | List sessions |
| `POST` | `/sessions` | Create a session |
| `GET` | `/sessions/{id}` | Get session |
| `POST` | `/sessions/{id}/close` | Close session |
| `POST` | `/sessions/{id}/messages` | Add message to session |
| `GET` | `/sessions/{id}/messages` | Get session messages |
| `POST` | `/sessions/for-tasks` | Create session for tasks (PM) |
| `POST` | `/sessions/{id}/link-task` | Link task to session |

### Messages (`/messages`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/messages` | List messages |
| `POST` | `/messages` | Create a message |
| `GET` | `/messages/{id}` | Get message |
| `PUT` | `/messages/{id}` | Edit message |

---

## Notifications API (`/notifications`)

Formal notification management.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/notifications` | List notifications |
| `GET` | `/notifications/unread` | Get unread notifications |
| `POST` | `/notifications` | Create notification (PM/Board) |
| `GET` | `/notifications/{id}` | Get notification |
| `POST` | `/notifications/{id}/ack` | Acknowledge notification |
| `POST` | `/notifications/{id}/read` | Mark as read |

---

## Journal API (`/journals`)

Agent personal journal management.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/journals` | Get current agent's journal |
| `GET` | `/journals/{agent_id}` | Get agent's journal |
| `POST` | `/journals/entries` | Create journal entry |
| `GET` | `/journals/entries` | List entries |
| `GET` | `/journals/entries/{id}` | Get entry |

---

## Optimal API (`/optimal`)

Knowledge base, RAG queries, and semantic search.

### Indexing

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/optimal/kb/index/code` | Index code files |
| `POST` | `/optimal/kb/index/docs` | Index documentation |
| `POST` | `/optimal/kb/refresh` | Refresh an index |
| `POST` | `/optimal/kb/reindex` | Trigger full reindex |
| `DELETE` | `/optimal/kb/{index_type}` | Clear an index |
| `GET` | `/optimal/kb/{index_type}/documents` | List indexed documents |

### Search & RAG

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/optimal/kb/search` | Semantic search |
| `GET` | `/optimal/kb/similar` | Find similar documents |
| `POST` | `/optimal/rag/query` | RAG query with answer |
| `POST` | `/optimal/rag/context` | Get context without answer |

### Knowledge Services

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/optimal/mentor/ask` | Ask the organizational knowledge base |
| `POST` | `/optimal/errors/search` | Search for error solutions |
| `POST` | `/optimal/errors/record` | Record error solution |
| `POST` | `/optimal/decisions/check` | Check for precedent decisions |
| `POST` | `/optimal/decisions/record` | Record a decision |
| `POST` | `/optimal/standards/get` | Get coding/security standards |
| `POST` | `/optimal/standards/validate` | Validate action against standards |
| `POST` | `/optimal/review/code` | Code review |
| `POST` | `/optimal/learnings/record` | Record a learning |
| `POST` | `/optimal/learnings/search` | Search learnings |
| `POST` | `/optimal/context/proactive` | Get proactive context for task |

### Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/optimal/stats` | Get all index statistics |
| `GET` | `/optimal/stats/{index_type}` | Get single index stats |
| `GET` | `/optimal/health` | RAG system health check |
| `POST` | `/optimal/tokens/estimate` | Estimate token count |
| `POST` | `/optimal/prompts` | Create prompt template |
| `GET` | `/optimal/prompts` | List prompt templates |

---

## Kanban API (`/kanban`)

Kanban board views for task management.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/kanban/board` | Get kanban board data |
| `GET` | `/kanban/board/{team}` | Get team kanban board |
| `GET` | `/kanban/swimlanes` | Get swimlane view |

---

## Dashboard API (`/dashboard`)

Dashboard data and metrics.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/dashboard/summary` | Get dashboard summary |
| `GET` | `/dashboard/metrics` | Get system metrics |
| `GET` | `/dashboard/activity` | Get recent activity |

---

## Orchestrator API (`/orchestrator`)

Agent orchestration and management.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/orchestrator/spawn` | Spawn an agent |
| `POST` | `/orchestrator/terminate` | Terminate an agent |
| `GET` | `/orchestrator/status` | Get orchestrator status |

---

## Stream API (`/stream`)

WebSocket streaming for real-time communication.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `WS` | `/stream/connect` | WebSocket connection |
| `WS` | `/stream/channel/{slug}` | Channel stream |
| `WS` | `/stream/agent/{id}` | Agent stream |

---

## Test API (`/test`)

Test execution endpoints.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/test/run` | Run tests in workspace |
| `GET` | `/test/results/{id}` | Get test results |

---

## A2A API (`/a2a`)

Agent-to-Agent protocol support.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/a2a/.well-known/agent.json` | Agent discovery |
| `POST` | `/a2a/tasks/send` | Send task to agent |
| `GET` | `/a2a/tasks/{id}/status` | Get task status |

---

## Health API (`/health`)

System health and readiness.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Basic health check |
| `GET` | `/health/ready` | Readiness probe |
| `GET` | `/health/live` | Liveness probe |

---

## Permission Model

The API enforces role-based permissions:

### Task Actions

| Action | Allowed Roles |
|--------|---------------|
| `CREATE` | PM, Board, CEO |
| `VIEW_ALL` | Main PM, Board, CEO, Auditor |
| `CLAIM` | Developers, QA, Documenters (own team) |
| `UPDATE_OWN` | Assigned agent or creator |
| `ASSIGN` | PM, Board, CEO |
| `CHANGE_PRIORITY` | PM, Board, CEO |
| `CLOSE` | PM, Board, CEO |

### KB Actions

| Action | Allowed Roles |
|--------|---------------|
| `INDEX_CODE` | PM, Board, CEO |
| `INDEX_DOCS` | PM, Board, CEO |
| `VIEW_STATS` | All authenticated agents |
| `CLEAR_INDEX` | PM, Board, CEO |
| `REFRESH_INDEX` | PM, Board, CEO |

### Notification Permissions

Only specific roles can send formal notifications:
- `cell_pm`
- `main_pm`
- `product_owner`
- `head_marketing`
- `auditor`

---

## Error Responses

All endpoints return standard error responses:

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

Common HTTP status codes:

| Code | Meaning |
|------|---------|
| `400` | Bad Request - Invalid input |
| `401` | Unauthorized - Missing authentication |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found - Resource doesn't exist |
| `500` | Internal Server Error |
| `504` | Gateway Timeout - Operation timed out |

---

## Rate Limiting

Currently, no rate limiting is implemented. This is planned for future versions.

## Versioning

The API does not currently implement versioning. Breaking changes will be documented in release notes.