REST API
The incubator exposes REST endpoints under /api/{namespace}/. The default namespace is default.
Base URL: http://localhost:8080/api/default
GET /state
Section titled “GET /state”Get all shared state or a specific key.
# All statecurl http://localhost:8080/api/default/state
# Specific keycurl http://localhost:8080/api/default/state?key=current_phaseResponse: { "current_phase": "review", "status": "running" }
POST /state
Section titled “POST /state”Set a state value.
curl -X POST http://localhost:8080/api/default/state \ -H 'Content-Type: application/json' \ -d '{"key": "current_phase", "value": "review"}'DELETE /state
Section titled “DELETE /state”Delete a state key.
curl -X DELETE http://localhost:8080/api/default/state \ -H 'Content-Type: application/json' \ -d '{"key": "temp_value"}'Events
Section titled “Events”GET /events
Section titled “GET /events”List events with optional filters.
# All eventscurl http://localhost:8080/api/default/events
# With filterscurl "http://localhost:8080/api/default/events?since=10&type=task.complete&limit=50"| Query param | Description |
|---|---|
since | Event ID to start from |
type | Filter by event type |
limit | Max events to return |
Response: [{ "id": 1, "type": "task.complete", "data": { "task": "auth" }, "timestamp": "..." }]
POST /events
Section titled “POST /events”Publish an event.
curl -X POST http://localhost:8080/api/default/events \ -H 'Content-Type: application/json' \ -d '{"type": "task.complete", "data": {"task": "auth", "status": "done"}}'Claims
Section titled “Claims”GET /claims
Section titled “GET /claims”List all active claims.
curl http://localhost:8080/api/default/claimsResponse: [{ "resource": "file:src/api.ts", "agent_id": "worker-1", "claimed_at": "..." }]
POST /claims
Section titled “POST /claims”Claim a resource.
curl -X POST http://localhost:8080/api/default/claims \ -H 'Content-Type: application/json' \ -d '{"resource": "file:src/api.ts", "agent_id": "worker-1"}'DELETE /claims
Section titled “DELETE /claims”Release a claim.
curl -X DELETE http://localhost:8080/api/default/claims \ -H 'Content-Type: application/json' \ -d '{"resource": "file:src/api.ts", "agent_id": "worker-1"}'GET /roles
Section titled “GET /roles”List registered agents and their roles.
curl http://localhost:8080/api/default/rolesPOST /roles
Section titled “POST /roles”Register an agent with a role.
curl -X POST http://localhost:8080/api/default/roles \ -H 'Content-Type: application/json' \ -d '{"agent_id": "worker-1", "role": "developer"}'Messages
Section titled “Messages”GET /messages
Section titled “GET /messages”List messages for an agent.
curl "http://localhost:8080/api/default/messages?agent_id=worker-1"POST /messages
Section titled “POST /messages”Send a message.
curl -X POST http://localhost:8080/api/default/messages \ -H 'Content-Type: application/json' \ -d '{"from": "queen", "to": "worker-1", "content": "Focus on the auth module"}'Control
Section titled “Control”POST /control
Section titled “POST /control”Issue a control command (halt, pause, resume).
# Haltcurl -X POST http://localhost:8080/api/default/control \ -H 'Content-Type: application/json' \ -d '{"command": "halt", "reason": "Critical bug"}'
# Pausecurl -X POST http://localhost:8080/api/default/control \ -d '{"command": "pause"}'
# Resumecurl -X POST http://localhost:8080/api/default/control \ -d '{"command": "resume"}'GET /control
Section titled “GET /control”Get current control status.
curl http://localhost:8080/api/default/controlGET /dance
Section titled “GET /dance”List available dance tools.
curl http://localhost:8080/api/dancePOST /dance/:toolName
Section titled “POST /dance/:toolName”Call a dance tool.
curl -X POST http://localhost:8080/api/dance/make_move \ -H 'Content-Type: application/json' \ -d '{"args": {"from": "e2", "to": "e4"}, "agentId": "player-1", "role": "white"}'