Appearance

REST API ​

The daemon exposes a REST API on the configured port (default: 31415). All endpoints are prefixed with /api/ and accept JSON request bodies.

Local only

The API is bound to 127.0.0.1 with CORS restricted to localhost origins. It is not accessible from the network.

Agents ​

GET /api/agents ​

List all active agents.

bash
curl http://localhost:31415/api/agents
json
[
  {
    "id": "backend-1",
    "role": "backend",
    "status": "active",
    "provider": "claude-code",
    "model": "claude-sonnet-4-6",
    "scope": ["src/api/**"],
    "contextUsage": 0.45,
    "spawnedAt": "2026-04-05T10:00:00Z"
  }
]

POST /api/agents ​

Spawn a new agent.

bash
curl -X POST http://localhost:31415/api/agents \
  -H "Content-Type: application/json" \
  -d '{"role": "backend", "scope": "src/api/**", "model": "claude-sonnet-4-6"}'

DELETE /api/agents/:id ​

Kill an agent.

bash
curl -X DELETE http://localhost:31415/api/agents/backend-1

POST /api/agents/:id/rotate ​

Trigger context rotation for an agent. Generates a handoff brief, kills the session, and respawns with fresh context.

bash
curl -X POST http://localhost:31415/api/agents/backend-1/rotate
json
{
  "old": "backend-1",
  "new": "backend-2",
  "handoffBrief": true,
  "reason": "manual"
}

POST /api/agents/:id/instruct ​

Send an instruction to a running agent. Uses rotation-based delivery -- the instruction is injected into the agent's context on its next rotation cycle.

bash
curl -X POST http://localhost:31415/api/agents/backend-1/instruct \
  -H "Content-Type: application/json" \
  -d '{"message": "Refactor the auth middleware to use JWT instead of sessions"}'

POST /api/agents/:id/query ​

Query an agent without disrupting its current work. Runs a headless call to gather information.

bash
curl -X POST http://localhost:31415/api/agents/backend-1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the current state of the database migration?"}'
json
{
  "answer": "Migration 003 is complete. Working on 004 — adding the sessions table.",
  "agentId": "backend-1"
}

Health ​

GET /api/health ​

Health check.

bash
curl http://localhost:31415/api/health
json
{
  "status": "ok",
  "uptime": 3600,
  "agents": 3,
  "version": "0.3.0"
}

Teams ​

GET /api/teams ​

List saved teams.

bash
curl http://localhost:31415/api/teams

POST /api/teams ​

Save current configuration as a team.

bash
curl -X POST http://localhost:31415/api/teams \
  -H "Content-Type: application/json" \
  -d '{"name": "fullstack"}'

POST /api/teams/:name/load ​

Load and spawn a saved team.

bash
curl -X POST http://localhost:31415/api/teams/fullstack/load

DELETE /api/teams/:name ​

Delete a saved team.

bash
curl -X DELETE http://localhost:31415/api/teams/fullstack

Credentials ​

GET /api/credentials ​

List stored credentials (keys are masked).

bash
curl http://localhost:31415/api/credentials

POST /api/credentials ​

Store an API key for a provider.

bash
curl -X POST http://localhost:31415/api/credentials \
  -H "Content-Type: application/json" \
  -d '{"provider": "codex", "key": "sk-your-key"}'

DELETE /api/credentials/:provider ​

Delete a stored credential.

bash
curl -X DELETE http://localhost:31415/api/credentials/codex

Providers ​

GET /api/providers ​

List available providers and their installation status.

bash
curl http://localhost:31415/api/providers

Configuration ​

GET /api/config ​

Get current configuration.

bash
curl http://localhost:31415/api/config

PATCH /api/config ​

Update configuration values.

bash
curl -X PATCH http://localhost:31415/api/config \
  -H "Content-Type: application/json" \
  -d '{"rotationThreshold": 0.7, "maxAgents": 8}'

Dashboard ​

GET /api/dashboard ​

Aggregated dashboard data -- agent summary, token usage, savings, and system status in a single call.

bash
curl http://localhost:31415/api/dashboard
json
{
  "agents": { "active": 3, "total": 7, "rotations": 4 },
  "tokens": { "used": 1250000, "saved": 380000, "budget": null },
  "savings": { "rotation": 210000, "coldStart": 120000, "conflict": 50000 },
  "uptime": 7200
}

Project Manager ​

POST /api/pm/review ​

Trigger a PM review of a specific agent's recent changes.

bash
curl -X POST http://localhost:31415/api/pm/review \
  -H "Content-Type: application/json" \
  -d '{"agentId": "backend-1"}'

GET /api/pm/history ​

Get PM review history.

bash
curl http://localhost:31415/api/pm/history

Journalist ​

GET /api/journalist ​

Get Journalist status and last cycle info.

bash
curl http://localhost:31415/api/journalist
json
{
  "running": true,
  "lastCycle": "2026-04-05T10:02:00Z",
  "interval": 120,
  "documentsGenerated": ["GROOVE_PROJECT_MAP.md", "GROOVE_DECISIONS.md"]
}

POST /api/journalist/cycle ​

Manually trigger a Journalist synthesis cycle.

bash
curl -X POST http://localhost:31415/api/journalist/cycle

Approvals ​

GET /api/approvals ​

List pending approval requests.

bash
curl http://localhost:31415/api/approvals

POST /api/approvals ​

Submit an approval decision.

bash
curl -X POST http://localhost:31415/api/approvals \
  -H "Content-Type: application/json" \
  -d '{"id": "approval-1", "decision": "approve"}'

Tokens ​

GET /api/tokens/summary ​

Token usage summary with savings breakdown.

bash
curl http://localhost:31415/api/tokens/summary
json
{
  "totalUsed": 1250000,
  "totalSaved": 380000,
  "breakdown": {
    "rotation": 210000,
    "coldStart": 120000,
    "conflict": 50000
  },
  "perAgent": [
    { "id": "backend-1", "used": 450000, "model": "claude-sonnet-4-6" }
  ]
}

Routing ​

GET /api/routing ​

Adaptive model routing status and cost tracking.

bash
curl http://localhost:31415/api/routing
json
{
  "mode": "auto",
  "decisions": 12,
  "costSaved": 0.45,
  "currentMappings": {
    "backend-1": { "model": "claude-sonnet-4-6", "reason": "medium_complexity" }
  }
}

Rotation ​

GET /api/rotation ​

Rotation statistics and history.

bash
curl http://localhost:31415/api/rotation
json
{
  "totalRotations": 4,
  "history": [
    {
      "old": "backend-1",
      "new": "backend-2",
      "reason": "context_threshold",
      "timestamp": "2026-04-05T10:30:00Z"
    }
  ]
}

Adaptive ​

GET /api/adaptive ​

Adaptive threshold data -- per-provider, per-role rotation thresholds and session scores.

bash
curl http://localhost:31415/api/adaptive
json
{
  "thresholds": {
    "claude-code": { "backend": 0.73, "frontend": 0.78 },
    "codex": { "backend": 0.75 }
  },
  "convergence": { "claude-code": true, "codex": false }
}

FSL-1.1-Apache-2.0

© 2026 Groove AI