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:

{
  "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.