<!--
hoody-agent Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T01:10:56.884Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: http


Tokens: 38027

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-agent Subskill

## Agent Orchestration & Task Execution

---

## 1. Overview

### What This Service Does

hoody-agent is the AI agent orchestration layer of the Hoody platform. It provides the complete runtime for managing conversational AI agents — creating sessions, dispatching prompts, streaming responses, executing tools, running workflows, managing memory, and coordinating autonomous background tasks. It is the central nervous system that binds together models, tools, skills, hooks, and human-in-the-loop approval gates into a coherent agentic loop.

hoody-agent manages:

- **Sessions** — stateful conversations with an AI agent, including streaming, prompt dispatch, tool execution, and confirmation gates
- **Agents** — reusable agent definitions with configurable models, tools, system prompts, and turn limits
- **Workflows** — multi-step orchestrated pipelines that run inside sessions
- **Skills** — pluggable capability modules sourced locally or from a skill hub
- **Tools** — the built-in and MCP tool catalog available to agents
- **Memory** — project-scoped persistent knowledge with semantic search, graph relations, and consolidation
- **Hooks** — lifecycle event handlers that fire on session events
- **Loops** — recurring scheduled agent runs within a session
- **Todos** — task management with proposals, approval gates, and autonomous orchestrator runs
- **GitHub Integration** — repo cloning, branching, committing, syncing, and PR creation
- **Providers & Models** — LLM provider management, OAuth flows, API key storage, and model fusion composites
- **Jobs** — async job tracking for long-running operations
- **Logs** — operational log querying, streaming, and statistics
- **Headless Runs** — fully autonomous single-shot agent execution without an open session

### When to Use This Service

| Need | Endpoint Group |
|------|---------------|
| Start a conversation with an AI agent | Sessions |
| Configure which AI agent to use | Agents |
| Run a multi-step automation | Workflows |
| Add new capabilities to an agent | Skills, Tools |
| Give an agent persistent knowledge | Memory |
| Run a one-off autonomous task | Headless Runs, Todos |
| Manage LLM provider credentials | Providers |
| Monitor agent activity and costs | Statistics, Usage, Logs |
| Integrate with Git repositories | GitHub |
| Schedule recurring agent actions | Loops |

### Authentication Model

All endpoints (except `GET /health`) require a valid Hoody bearer token in the `Authorization` header. Requests are scoped by working directory headers:

- `X-Hoody-Cwd` — sets the working directory context for the request
- `X-Hoody-Config-Dir` — sets the configuration directory context
- `X-Hoody-Realm` — selects the active realm (where supported; many endpoints reject realm headers and are cwd-scoped)

Some endpoints also support `X-Hoody-Gate-Policy: auto_approve` to bypass confirmation gates during automated workflows.

### How It Fits Into Hoody Philosophy

hoody-agent embodies Hoody's agent-first philosophy: the agent is the primary unit of work. Sessions bind an agent definition to a specific container and working directory at creation time, then the agent drives tool calls, receives human confirmations, and can spawn background sub-agents — all through a unified event stream. The system enforces human approval for destructive operations through gated choke points, while allowing autonomous operation where explicitly configured.

---

## 2. Core Resource Workflows

### 2.1 Health & System Status

The health endpoint is the only unauthenticated route and returns a 9-field health payload.

#### Check System Health

```
curl -s http://localhost:3000/api/v1/agent/health
```

```
{
  "status": "ok",
  "version": "0.0.0",
  "uptime": 12345,
  "daemon": "running",
  "gateway": "running",
  "memory": true,
  "hooks": true,
  "sessions": 3,
  "models": 42
}
```

#### View Prometheus Metrics

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/metrics
```

#### Download OpenAPI Spec

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/openapi.json > hoody-agent-openapi.json
```

---

### 2.2 Sessions — Conversation Lifecycle

Sessions are the core unit of interaction. A session binds an agent to a container, realm, and working directory at creation. All subsequent turns, tool calls, and events flow through the session.

#### List Sessions

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  http://localhost:3000/api/v1/agent/sessions
```

```
{
  "items": [
    {
      "id": "ses_abc123",
      "agent": "default",
      "cwd": "/home/user/project",
      "status": "active",
      "attached": true,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50
  }
}
```

#### Create a Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions \
  -d '{
    "agent": "default",
    "realm": "my-realm-id",
    "container": "container-id"
  }'
```

```
{
  "id": "ses_new123",
  "agent": "default",
  "realm": "my-realm-id",
  "container": "container-id",
  "cwd": "/home/user/project",
  "status": "active",
  "tool_mode": "auto",
  "created_at": "2025-01-15T12:00:00Z"
}
```

#### Get Session Details

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123
```

#### Dispatch a User Turn (Async)

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/messages \
  -d '{
    "content": "Explain the architecture of this codebase"
  }'
```

```
{
  "job_id": "job_msg789"
}
```

#### Dispatch a Prompt (Synchronous)

Blocks until the agent completes its turn or parks on a confirmation gate.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/prompt:sync \
  -d '{
    "content": "List all Python files in the src directory"
  }'
```

```
{
  "status": "completed",
  "response": "Here are the Python files in the src directory...",
  "pending_gate": null
}
```

#### Dispatch a Prompt (Streaming)

Returns Server-Sent Events for real-time token streaming.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/prompt:stream \
  -d '{
    "content": "Write a hello world program"
  }'
```

The response is an SSE stream with events like `event.token`, `event.tool_call`, and `event.agent_done`.

#### Attach to Session Event Stream

Connect via WebSocket or SSE to receive all session events in real time.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/stream
```

#### Replay Buffered Events

Get the gateway's buffered event tail for a live session with sequence numbers for resume.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/replay
```

#### Cancel an Active Turn

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/cancel
```

#### Close a Session

Tears down the live connection without removing the persisted record.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/close
```

#### Delete a Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/sessions/ses_new123
```

With hard delete (removes persisted record):

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE "http://localhost:3000/api/v1/agent/sessions/ses_new123?hard=true"
```

#### Answer a Parked Question

When the agent asks the user a question, the session parks on a gate.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/answer \
  -d '{
    "answer": "Yes, proceed with the migration"
  }'
```

#### Confirm a Tool/Dir Gate

When the agent wants to run a tool or access a directory, it parks for confirmation.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/confirm \
  -d '{
    "approved": true
  }'
```

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/confirm \
  -d '{
    "approved": false,
    "reason": "This file is protected"
  }'
```

#### Switch Agent Mid-Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/agent \
  -d '{
    "agent": "code-reviewer"
  }'
```

#### Switch Model Mid-Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/model \
  -d '{
    "model": "anthropic/claude-opus-4-8"
  }'
```

#### Change Reasoning Effort

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/effort \
  -d '{
    "effort": "high"
  }'
```

#### Change Verbosity

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/verbosity \
  -d '{
    "verbosity": "concise"
  }'
```

#### Toggle HOODY_* Shell Environment

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/hoody-env \
  -d '{
    "enabled": true
  }'
```

#### Arm Auto-Reply Loop

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/auto-reply \
  -d '{
    "rounds": 5,
    "model": "anthropic/claude-sonnet-4-20250514",
    "allow_writes": true
  }'
```

#### Trim Conversation History

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/trim \
  -d '{
    "turn_index": 3
  }'
```

#### Get Distinct Working Directories

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/cwds
```

```
{
  "cwds": [
    "/home/user/project-a",
    "/home/user/project-b",
    "/tmp/scratch"
  ]
}
```

#### Run a Tool in Session Context

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/tools/bash/run \
  -d '{
    "command": "ls -la"
  }'
```

#### List Session Tools

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/tools
```

#### List MCP Tools in Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/tools/mcp
```

#### Inject Workflow Feedback

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/workflow/messages \
  -d '{
    "content": "The migration is complete, please verify the database state"
  }'
```

#### Dispatch a Workflow Run on a Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/workflows/code-review/runs \
  -d '{
    "input": {
      "path": "src/"
    }
  }'
```

```
{
  "job_id": "job_wf_run456"
}
```

---

### 2.3 Agents — Agent Definitions

Agents are reusable configurations that define a model, system prompt, tools, and turn limits. Built-in agents ship with the system; custom agents are stored as markdown files with frontmatter.

#### List Agents

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  http://localhost:3000/api/v1/agent/agents
```

```
{
  "agents": [
    {
      "name": "default",
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": "all",
      "max_turns": 50,
      "system": true,
      "custom": false
    },
    {
      "name": "code-reviewer",
      "model": "anthropic/claude-opus-4-8",
      "tools": ["bash", "read_file", "search"],
      "max_turns": 10,
      "system": false,
      "custom": true
    }
  ]
}
```

#### Create a Custom Agent

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/agents \
  -d '{
    "name": "security-auditor",
    "model": "anthropic/claude-opus-4-8",
    "tools": ["bash", "read_file", "search", "grep"],
    "max_turns": 25,
    "system_prompt": "You are a security auditor. Review code for vulnerabilities, focusing on injection, auth bypass, and data exposure risks."
  }'
```

#### Get Agent Source

Returns the raw markdown source with frontmatter and system prompt.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/agents/security-auditor/source
```

#### Update Agent Source

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/agents/security-auditor/source \
  -d '{
    "source": "---\nmodel: anthropic/claude-opus-4-8\ntools: [bash, read_file, search]\nmax_turns: 25\n---\n\nYou are a senior security auditor..."
  }'
```

#### Set Agent Model

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/agents/security-auditor/model \
  -d '{
    "model": "openai/gpt-4o"
  }'
```

Remove model override (inherit from settings):

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/agents/security-auditor/model \
  -d '{
    "model": ""
  }'
```

#### Set Agent Tools

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/agents/security-auditor/tools \
  -d '{
    "tools": ["bash", "read_file", "search", "grep", "write_file"]
  }'
```

#### Toggle a Single Tool

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/agents/security-auditor/tools/bash/toggle
```

#### Set Agent Max Turns

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/agents/security-auditor/turns \
  -d '{
    "max_turns": 50
  }'
```

#### Copy an Agent

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/agents/security-auditor/copy \
  -d '{
    "new_name": "security-auditor-v2"
  }'
```

#### Rename an Agent

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/agents/security-auditor-v2/rename \
  -d '{
    "new_name": "sec-reviewer"
  }'
```

#### Reset Agent to Shipped Default

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/agents/sec-reviewer/reset-to-shipped
```

#### Delete a Custom Agent

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/agents/security-auditor
```

---

### 2.4 Tools — Built-in Tool Catalog

The tool catalog provides schemas for all built-in tools. Tools can be run directly without a session or through a live session.

#### List All Tools

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/tools
```

```
{
  "items": [
    {
      "name": "bash",
      "description": "Execute a bash command",
      "input_schema": {
        "type": "object",
        "properties": {
          "command": { "type": "string" }
        },
        "required": ["command"]
      },
      "read_only": false
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 50 }
}
```

#### List Read-Only Tools

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/tools/read-only
```

#### Get a Single Tool Schema

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/tools/bash
```

#### Run a Tool Directly (No Session)

Runs through the gated choke point with an ephemeral session created from scope headers.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/tools/bash/run \
  -d '{
    "command": "echo hello"
  }'
```

#### Run a Tool Asynchronously

Returns a job ID immediately; poll the jobs endpoint for results.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/tools/bash/runAsync \
  -d '{
    "command": "npm test"
  }'
```

```
{
  "job_id": "job_tool_async_789"
}
```

#### Run a Tool with Streaming

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/tools/bash/stream \
  -d '{
    "command": "make build"
  }'
```

Returns SSE frames: `start`, then `result` or `needs_confirmation` or `error`, then `end`.

---

### 2.5 Workflows — Multi-Step Orchestration

Workflows define reusable multi-step pipelines that execute within sessions.

#### List Workflows

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  http://localhost:3000/api/v1/agent/workflows
```

```
{
  "items": [
    {
      "name": "code-review",
      "summary": "Automated code review pipeline",
      "steps": ["lint", "test", "review"],
      "system": true
    }
  ],
  "meta": { "total": 5, "page": 1, "limit": 50 }
}
```

#### Get a Workflow Definition

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  http://localhost:3000/api/v1/agent/workflows/code-review
```

#### Create or Replace a Workflow

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/workflows/deploy-check \
  -d '{
    "definition": {
      "summary": "Pre-deployment verification checklist",
      "steps": [
        { "name": "run-tests", "tool": "bash", "input": { "command": "npm test" } },
        { "name": "type-check", "tool": "bash", "input": { "command": "tsc --noEmit" } },
        { "name": "security-scan", "agent": "security-auditor" }
      ]
    }
  }'
```

#### Delete a Workflow

System workflows cannot be deleted.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/workflows/deploy-check
```

#### Hide a Workflow from UI

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/workflows/code-review/hide
```

#### List Workflow Runs

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/workflows/runs
```

#### Get a Workflow Run

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/workflows/runs/run_abc123
```

#### Cancel a Workflow Run

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/workflows/runs/run_abc123/cancel
```

---

### 2.6 Skills — Capability Plugins

Skills are pluggable modules that extend agent capabilities. They can be created locally, installed from a hub, or imported from well-known locations.

#### List Installed Skills

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  http://localhost:3000/api/v1/agent/skills
```

```
{
  "items": [
    {
      "name": "git-workflow",
      "root_dir": "/home/user/.hoody/skills",
      "rel_dir": "git-workflow",
      "enabled": true,
      "trusted": true
    }
  ],
  "meta": { "total": 3, "page": 1, "limit": 50 }
}
```

#### Create a Skill

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills \
  -d '{
    "name": "test-runner"
  }'
```

#### Read Skill Source

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/skills/source?root=/home/user/.hoody/skills&rel=test-runner"
```

#### Write Skill Source

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/skills/source \
  -d '{
    "root": "/home/user/.hoody/skills",
    "rel": "test-runner",
    "content": "This skill runs tests and reports results."
  }'
```

#### Toggle Skill Enabled State

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/toggle \
  -d '{
    "name": "test-runner",
    "disabled": true
  }'
```

#### Set Skill Trust

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/trust \
  -d '{
    "root": "/home/user/.hoody/skills",
    "rel": "test-runner",
    "trusted": true
  }'
```

#### Rename a Skill

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/rename \
  -d '{
    "root": "/home/user/.hoody/skills",
    "rel": "test-runner",
    "new_name": "test-automation"
  }'
```

#### Delete a Skill

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/delete \
  -d '{
    "root": "/home/user/.hoody/skills",
    "rel": "test-automation"
  }'
```

#### Search the Skill Hub

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/skills/hub/search?q=code+review"
```

#### Preview a Hub Skill

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/skills/hub/preview?id=hub-skill-123"
```

#### Install from Hub

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/hub/install \
  -d '{
    "id": "hub-skill-123"
  }'
```

#### Scan for Importable Skills

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/skills/import/scan
```

#### Import a Discovered Skill

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/import/apply \
  -d '{
    "source": "/path/to/discovered/skill"
  }'
```

#### View Hub Cache Stats

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/skills/hub/cache
```

#### Clear Hub Cache

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/skills/hub/cache
```

---

### 2.7 Memory — Persistent Knowledge

Memory provides project-scoped persistent knowledge with semantic search, graph relations, and LLM-driven consolidation.

#### List Memory Projects

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/memory/projects
```

#### List Memory Items

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/memory/items?project=my-project&kind=note"
```

```
{
  "rows": [
    {
      "id": "mem_abc123",
      "project": "my-project",
      "kind": "note",
      "type": "fact",
      "content": "The auth service uses JWT tokens with 1-hour expiry",
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 15
}
```

#### Get a Memory Item

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/memory/items/mem_abc123?project=my-project&kind=note"
```

#### Store a Memory Item

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/memory/items \
  -d '{
    "project": "my-project",
    "kind": "note",
    "type": "fact",
    "content": "The CI pipeline runs on GitHub Actions with a 20-minute timeout"
  }'
```

#### Edit a Memory Item

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/memory/items/mem_abc123 \
  -d '{
    "content": "The auth service uses JWT tokens with 2-hour expiry (updated)"
  }'
```

#### Delete Memory Items

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X DELETE http://localhost:3000/api/v1/agent/memory/items \
  -d '{
    "ids": ["mem_abc123", "mem_def456"]
  }'
```

#### Search Memory (Hybrid)

Performs BM25 + vector + graph fusion search. The query is privacy-stripped before processing.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/memory/search \
  -d '{
    "project": "my-project",
    "query": "authentication token expiry"
  }'
```

#### View Memory Graph

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/memory/graph?project=my-project&node_type=entity&limit=20"
```

#### Toggle Memory Enabled

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/memory/enabled \
  -d '{
    "enabled": true
  }'
```

#### Flush Memory to Disk

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/memory/flush
```

#### Trigger Memory Consolidation

This is a human-only operation — it spends multi-LLM passes and evolves memory state irreversibly.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/memory/consolidate \
  -d '{
    "project": "my-project"
  }'
```

---

### 2.8 Hooks — Lifecycle Event Handlers

Hooks are session-scoped lifecycle event handlers that fire custom commands on events like session start, tool calls, and turn completion. All mutations require a two-step write nonce.

#### Begin Hook Write (Get Nonce)

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/begin-write \
  -d '{
    "session_id": "ses_new123",
    "op": "upsert"
  }'
```

```
{
  "nonce": "hook_nonce_abc789",
  "expires_at": "2025-01-15T12:10:00Z"
}
```

#### List Hooks

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/hooks?session_id=ses_new123"
```

#### Create/Update a Hook

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/hooks \
  -d '{
    "session_id": "ses_new123",
    "nonce": "hook_nonce_abc789",
    "name": "on-tool-call",
    "event": "tool_call",
    "command": "logger \"Tool called: $TOOL_NAME\"",
    "enabled": true
  }'
```

#### Toggle a Hook

Requires its own nonce (op: toggle).

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/toggle \
  -d '{
    "session_id": "ses_new123",
    "nonce": "hook_nonce_toggle_xyz",
    "name": "on-tool-call"
  }'
```

#### Disable All Hooks

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/disable-all \
  -d '{
    "session_id": "ses_new123",
    "nonce": "hook_nonce_disable_xyz",
    "disabled": true
  }'
```

#### Test-Fire a Hook

Executes the hook command immediately. No `_machine_confirmed` gate on this RPC.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/test \
  -d '{
    "session_id": "ses_new123",
    "name": "on-tool-call"
  }'
```

#### Reload Hooks from Disk

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/reload \
  -d '{
    "session_id": "ses_new123"
  }'
```

#### Acknowledge Hook Trust Prompt

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/trust/ack \
  -d '{
    "session_id": "ses_new123"
  }'
```

#### Delete a Hook

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X DELETE http://localhost:3000/api/v1/agent/hooks \
  -d '{
    "session_id": "ses_new123",
    "nonce": "hook_nonce_delete_xyz",
    "name": "on-tool-call"
  }'
```

---

### 2.9 Loops — Recurring Agent Runs

Loops schedule recurring agent executions within a session with configurable intervals, budgets, and stop conditions.

#### List Loops for a Session

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/loops
```

```
{
  "items": [
    {
      "id": "loop_abc123",
      "interval": "1h",
      "max_runs": 10,
      "runs_completed": 3,
      "paused": false,
      "expires_at": "2025-01-20T00:00:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50 }
}
```

#### Create a Loop

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/loops \
  -d '{
    "interval": "30m",
    "max_runs": 20,
    "stop_when": "exit_code != 0",
    "cost_budget": 5.00,
    "wall_budget": "4h"
  }'
```

#### Pause/Resume/Stop a Loop

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/loops/loop_abc123 \
  -d '{
    "paused": true
  }'
```

#### Update Loop Expiry

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/sessions/ses_new123/loops/loop_abc123 \
  -d '{
    "expires_in": "2h"
  }'
```

#### Run a Loop Now

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/loops/loop_abc123/run-now
```

#### Delete a Loop

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/sessions/ses_new123/loops/loop_abc123
```

---

### 2.10 Todos — Task Management

Todos provide a structured task management system with proposals, approval gates, orchestrator integration, and autonomous background runs.

#### List Todos

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  "http://localhost:3000/api/v1/agent/todos?states=open,in-progress&tags=bug"
```

#### Get Current Revision

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/todos/revision
```

```
{
  "revision": "rev_20250115_abc123"
}
```

#### Create a Todo

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos \
  -d '{
    "title": "Fix authentication timeout on slow connections",
    "description": "Users on slow connections get 401 errors when the JWT refresh window overlaps with request timeout.",
    "tags": ["bug", "auth", "p1"],
    "priority": "high"
  }'
```

#### Get a Todo

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/todos/todo_abc123
```

#### Update a Todo (CAS-guarded)

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/todos/todo_abc123 \
  -d '{
    "revision": "rev_20250115_abc123",
    "state": "in-progress",
    "assignee": "agent:security-auditor"
  }'
```

#### Claim a Todo

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/claim
```

#### Release a Claimed Todo

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/release
```

#### Post a Comment (No Orchestrator)

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/messages \
  -d '{
    "content": "Reproduced the issue on my dev environment"
  }'
```

#### Post a Comment and Trigger Orchestrator

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/message \
  -d '{
    "content": "Please investigate the auth timeout and propose a fix"
  }'
```

```
{
  "job_id": "job_todo_msg_456"
}
```

#### Run a Todo Autonomously

Spawns a background worker session. Reaching this RPC is treated as human approval.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/run \
  -d '{
    "agent": "default"
  }'
```

```
{
  "job_id": "job_todo_run_789",
  "session_id": "ses_todo_worker_001"
}
```

#### Cancel an In-Flight Orchestrator Run

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/cancel-run
```

#### Approve a Proposal

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/proposals/proposal_001/approve
```

#### Deny a Proposal

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/proposals/proposal_001/deny \
  -d '{
    "reason": "Approach is too risky, please try a different strategy"
  }'
```

#### Snooze a Todo

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/snooze \
  -d '{
    "wake_at": "2025-01-20T09:00:00Z"
  }'
```

#### Archive a Todo

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/todo_abc123/archive
```

#### Trigger LLM Triage

Spends model budget on an autonomous triage pass.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/triage
```

```
{
  "job_id": "job_triage_001"
}
```

#### Purge Archived Todos

Permanently and irreversibly destroys archived todos.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/purge
```

---

### 2.11 Providers & Models — LLM Configuration

Providers manage LLM credentials (API keys, OAuth), account pools, and model catalogs. Fusion composites combine multiple models into unified endpoints.

#### List Providers

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/providers
```

```
{
  "items": [
    {
      "id": "anthropic",
      "display_name": "Anthropic",
      "model_prefix": "anthropic/",
      "wire_format": "openai",
      "model_count": 8
    },
    {
      "id": "openai",
      "display_name": "OpenAI",
      "model_prefix": "openai/",
      "wire_format": "openai",
      "model_count": 15
    }
  ],
  "meta": { "total": 6, "page": 1, "limit": 50 }
}
```

#### Get Provider Details

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/providers/anthropic
```

#### List Provider Models

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/models
```

```
{
  "items": [
    {
      "spec": "anthropic/claude-sonnet-4-20250514",
      "display_name": "Claude Sonnet 4",
      "context_window": 200000,
      "output_limit": 64000,
      "reasoning": false,
      "input_price_per_mtok": 3.0,
      "output_price_per_mtok": 15.0
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 50 }
}
```

#### Check Provider Auth Status

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/providers/anthropic/auth
```

```
{
  "api_key_set": true,
  "oauth_set": false,
  "default_method": "api_key",
  "passwordless": false,
  "account_pool_size": 0
}
```

#### Store an API Key

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/providers/anthropic/auth/api-key \
  -d '{
    "api_key": "sk-ant-api03-..."
  }'
```

#### Delete an API Key

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/providers/anthropic/auth/api-key
```

#### Start OAuth Login

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/providers/anthropic/auth/oauth
```

```
{
  "success": true,
  "job_id": "job_oauth_001",
  "verification_uri": "https://example.com/device",
  "user_code": "ABCD-1234"
}
```

#### Poll OAuth Job

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/providers/anthropic/auth/oauth/job_oauth_001
```

```
{
  "state": "complete",
  "account": {
    "key": "user@example.com",
    "label": "User Account",
    "active": true
  }
}
```

#### Submit OAuth Code

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/providers/anthropic/auth/oauth/job_oauth_001/code \
  -d '{
    "code": "auth_code_from_redirect"
  }'
```

#### Logout OAuth

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/providers/anthropic/auth/oauth
```

#### Set Default Auth Method

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/providers/anthropic/auth/default \
  -d '{
    "method": "api_key"
  }'
```

#### List OAuth Account Pool

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/providers/anthropic/auth/accounts
```

#### Add OAuth Account to Pool

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/providers/anthropic/auth/accounts
```

```
{
  "job_id": "job_pool_add_002"
}
```

#### Set Active Account

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/providers/anthropic/auth/accounts/user@example.com/active \
  -d '{
    "active": true
  }'
```

#### Remove Account from Pool

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/providers/anthropic/auth/accounts/user@example.com
```

#### List Fusion Composites

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/settings/fusion?include_invalid=true"
```

#### Create/Update Fusion Composite

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/settings/fusion/fast-balance \
  -d '{
    "spec": {
      "name": "Fast Balance",
      "method": "cascade",
      "members": [
        { "model": "anthropic/claude-sonnet-4-20250514", "weight": 1.0 },
        { "model": "openai/gpt-4o-mini", "weight": 0.5 }
      ],
      "context_window": 128000
    }
  }'
```

#### Delete Fusion Composite

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/settings/fusion/fast-balance
```

---

### 2.12 GitHub Integration

GitHub endpoints manage repository operations scoped to the request's working directory.

#### Check GitHub Auth Status

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/github/auth/status
```

```
{
  "authenticated": true,
  "username": "developer",
  "scope": "repo,read:org"
}
```

#### Start GitHub Device Flow Login

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/github/auth/login
```

```
{
  "device_code": "device_abc123",
  "user_code": "ABCD-1234",
  "verification_uri": "https://github.com/login/device",
  "interval": 5,
  "expires_in": 900
}
```

#### Poll GitHub Login

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/auth/login/poll \
  -d '{
    "device_code": "device_abc123",
    "interval": 5,
    "expires_in": 900
  }'
```

#### List GitHub Repos

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/github/repos
```

#### Clone a Repository

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/clone \
  -d '{
    "repo": "owner/repository-name"
  }'
```

#### Get Git Status

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/repository-name" \ \
  http://localhost:3000/api/v1/agent/github/status
```

```
{
  "branch": "main",
  "ahead": 0,
  "behind": 2,
  "modified": ["src/auth.ts", "tests/auth.test.ts"],
  "untracked": ["src/new-feature.ts"]
}
```

#### List Branches

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/repository-name" \ \
  http://localhost:3000/api/v1/agent/github/branches
```

#### Commit Changes

Stages all changes and commits. This is a destructive operation.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/repository-name" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/commit \
  -d '{
    "message": "fix: resolve authentication timeout on slow connections"
  }'
```

#### Sync Repository

Runs fetch, pull, push as one logical operation. Stops at the first failure.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/repository-name" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/sync \
  -d '{
    "direction": "both"
  }'
```

#### Create a Pull Request

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/repository-name" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/pr \
  -d '{
    "title": "fix: authentication timeout on slow connections",
    "body": "Addresses the JWT refresh race condition reported in #123.",
    "base": "main",
    "head": "fix/auth-timeout"
  }'
```

---

### 2.13 Jobs — Async Operation Tracking

Jobs track the status of asynchronous operations like workflow runs, tool executions, and long-running dispatches.

#### Get Job Status

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/jobs/job_msg789
```

```
{
  "id": "job_msg789",
  "status": "completed",
  "type": "session_dispatch",
  "created_at": "2025-01-15T12:00:00Z",
  "completed_at": "2025-01-15T12:00:15Z"
}
```

#### Get Job Result

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/jobs/job_msg789/result
```

#### Cancel or Delete a Job

Cancels pending/running jobs; deletes terminal job records.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X DELETE http://localhost:3000/api/v1/agent/jobs/job_msg789
```

---

### 2.14 Headless Runs — Autonomous Execution

Headless runs drive the full agent loop over an ephemeral session without requiring an open persistent session.

#### Create a Headless Run

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/headless/runs \
  -d '{
    "prompt": "Analyze the security vulnerabilities in the authentication module and generate a report",
    "agent": "security-auditor",
    "format": "json"
  }'
```

The default form returns async (HTTP 202):

```
{
  "job_id": "job_headless_001"
}
```

Poll with `GET /jobs/job_headless_001/result` once the job completes.

---

### 2.15 Settings — Process-Wide Configuration

Settings manage the hoody-agent's merged configuration from home, project, and local layers.

#### Get Settings

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/settings
```

```
{
  "settings": {
    "features": {
      "memory": true,
      "auto_reply": false
    },
    "default_model": "anthropic/claude-sonnet-4-20250514",
    "ui": {
      "hidden_workflows": []
    }
  },
  "home": {
    "features": {
      "memory": true
    }
  }
}
```

#### Patch Settings

Applies a shallow top-level merge into the home settings file. Sending a nil value deletes a key.

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/settings \
  -d '{
    "default_model": "anthropic/claude-opus-4-8",
    "features": {
      "memory": true,
      "auto_reply": true
    }
  }'
```

---

### 2.16 ACP Agents — BYOA Delegated Sessions

ACP agents report the status of Bring-Your-Own-Backend agents (Codex, Claude, Gemini, OpenCode).

#### Get ACP Agent Status

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/acp/agents
```

```
{
  "codex": {
    "enabled": true,
    "on_path": true,
    "trust": "full"
  },
  "claude": {
    "enabled": false,
    "on_path": false,
    "trust": "none"
  }
}
```

#### Set ACP Agent Secret

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/acp/agents/codex/secrets/OPENAI_API_KEY \
  -d '{
    "value": "sk-..."
  }'
```

---

### 2.17 Logs — Operational Monitoring

Logs provide querying, streaming, and statistics for the active-supervisor log stream.

#### Query Logs

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/logs?source=agent&level=error&limit=50"
```

#### Get a Single Log Entry

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/logs/entries/entry_ref_001
```

#### List Log Sources

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/logs/sources
```

```
{
  "sources": ["agent", "gateway", "hooks", "memory", "tools"]
}
```

#### Get Log Statistics

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/logs/stats
```

#### Stream Logs via SSE

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/logs/stream?level=warn"
```

---

### 2.18 Statistics & Usage — Cost and Activity Tracking

#### Get Cross-Session Statistics

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/statistics?scope=all"
```

```
{
  "sessions": 45,
  "turns": 1230,
  "tool_calls": 567,
  "tokens": {
    "input": 2500000,
    "output": 800000
  },
  "cost": {
    "total": 12.50,
    "currency": "USD"
  }
}
```

#### Usage by Model

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/usage/by-model?since=1704067200"
```

```
{
  "items": [
    {
      "model": "anthropic/claude-sonnet-4-20250514",
      "provider": "anthropic",
      "calls": 450,
      "success_rate": 0.99,
      "cost": 8.25,
      "avg_latency_ms": 2300
    }
  ],
  "meta": { "total": 3, "page": 1, "limit": 50 }
}
```

#### Usage by Account

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/usage/by-account?since=1704067200"
```

---

### 2.19 Tasks — Background Subagent Management

Tasks represent background subagent work within a live session.

#### List Background Tasks

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/tasks
```

The response arrives as a `tasks_snapshot` event on the session's stream.

#### Cancel One Background Task

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/tasks/task_bg_001/cancel
```

#### Cancel All Background Tasks

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions/ses_new123/tasks/cancel
```

#### Get Task Transcript

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_new123/tasks/task_bg_001/transcript
```

---

### 2.20 Discovery — Realms & Containers

#### List Realms

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/realms
```

```
{
  "items": [
    {
      "id": "realm_abc123",
      "name": "production",
      "active": true,
      "blocked": false
    }
  ],
  "meta": { "total": 2, "page": 1, "limit": 50 }
}
```

#### List Containers in a Realm

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/containers?realm=realm_abc123"
```

```
{
  "items": [
    {
      "id": "container_xyz789",
      "name": "dev-workspace",
      "status": "running"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50 }
}
```

---

### 2.21 Docs — API Documentation

#### Access Swagger UI

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/docs
```

---

## 3. Advanced Operations

### 3.1 Full Agent Workflow: Create Agent, Session, and Run

This workflow demonstrates end-to-end agent setup and execution.

**Step 1: Create a custom agent**

```
AGENT_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/agents \
  -d '{
    "name": "migration-planner",
    "model": "anthropic/claude-opus-4-8",
    "tools": ["bash", "read_file", "search", "grep", "write_file"],
    "max_turns": 30,
    "system_prompt": "You are a database migration planner. Analyze schemas, generate migration scripts, and validate data integrity."
  }')
echo "$AGENT_RESP"
```

**Step 2: Verify agent creation**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/agents/migration-planner/source
```

**Step 3: Open a session with the agent**

```
SESSION_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/migration-project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions \
  -d '{
    "agent": "migration-planner"
  }')
SESSION_ID=$(echo "$SESSION_RESP" | jq -r '.id')
echo "Session: $SESSION_ID"
```

**Step 4: Dispatch a prompt**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST "http://localhost:3000/api/v1/agent/sessions/$SESSION_ID/prompt:sync" \
  -d '{
    "content": "Analyze the current database schema in ./schema.sql and generate a migration plan for adding user preferences tables."
  }'
```

**Step 5: If the agent parks on a tool gate, approve it**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST "http://localhost:3000/api/v1/agent/sessions/$SESSION_ID/confirm" \
  -d '{
    "approved": true
  }'
```

**Step 6: Close the session**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST "http://localhost:3000/api/v1/agent/sessions/$SESSION_ID/close"
```

### 3.2 Autonomous Todo Execution Pipeline

This workflow shows how todos flow from creation through LLM triage, proposal review, and autonomous execution.

**Step 1: Create a todo**

```
TODO_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/todos \
  -d '{
    "title": "Refactor authentication module to use refresh tokens",
    "description": "The current auth module uses long-lived JWTs. Switch to short-lived access tokens with refresh token rotation.",
    "tags": ["security", "refactor", "auth"],
    "priority": "high"
  }')
TODO_ID=$(echo "$TODO_RESP" | jq -r '.id')
echo "Todo: $TODO_ID"
```

**Step 2: Trigger LLM triage**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/todos/triage
```

**Step 3: Poll the triage job**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/jobs/job_triage_001/result
```

**Step 4: Post a message to kick the orchestrator**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST "http://localhost:3000/api/v1/agent/todos/$TODO_ID/message" \
  -d '{
    "content": "Please create a detailed implementation plan and propose specific changes."
  }'
```

**Step 5: Review and approve the proposal**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST "http://localhost:3000/api/v1/agent/todos/$TODO_ID/proposals/proposal_001/approve"
```

**Step 6: Or run the todo directly (reaching this RPC = human approval)**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST "http://localhost:3000/api/v1/agent/todos/$TODO_ID/run" \
  -d '{
    "agent": "migration-planner"
  }'
```

```
{
  "job_id": "job_todo_run_789",
  "session_id": "ses_todo_worker_001"
}
```

**Step 7: Monitor the worker session**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/sessions/ses_todo_worker_001/stream
```

### 3.3 GitHub Development Cycle

A complete cycle from repo setup through development and PR creation.

**Step 1: Authenticate with GitHub (device flow)**

```
LOGIN_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/github/auth/login)

echo "$LOGIN_RESP" | jq -r '.user_code, .verification_uri'
```

**Step 2: User authorizes at the URL, then poll**

```
DEVICE_CODE=$(echo "$LOGIN_RESP" | jq -r '.device_code')

curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/auth/login/poll \
  -d "{
    \"device_code\": \"$DEVICE_CODE\",
    \"interval\": 5,
    \"expires_in\": 900
  }"
```

**Step 3: Clone the repo**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/clone \
  -d '{
    "repo": "myorg/webapp"
  }'
```

**Step 4: Open a session to work on the code**

```
SESSION_ID=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/webapp" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/sessions \
  -d '{"agent": "default"}' | jq -r '.id')
```

**Step 5: Let the agent make changes**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST "http://localhost:3000/api/v1/agent/sessions/$SESSION_ID/prompt:stream" \
  -d '{
    "content": "Add rate limiting to the API endpoints in src/api/"
  }'
```

**Step 6: Check git status**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/webapp" \ \
  http://localhost:3000/api/v1/agent/github/status
```

**Step 7: Commit the changes**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/webapp" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/commit \
  -d '{
    "message": "feat: add rate limiting middleware to API endpoints"
  }'
```

**Step 8: Sync with remote**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/webapp" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/sync \
  -d '{
    "direction": "push"
  }'
```

**Step 9: Create a pull request**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/projects/webapp" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/github/pr \
  -d '{
    "title": "feat: add rate limiting middleware",
    "body": "Adds configurable rate limiting to all API endpoints using a sliding window algorithm. Includes tests and documentation.",
    "base": "main",
    "head": "feature/rate-limiting"
  }'
```

### 3.4 Provider OAuth Setup with Account Pool

Setting up an LLM provider with multiple OAuth accounts for rotation.

**Step 1: Start initial OAuth flow**

```
OAUTH_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/providers/anthropic/auth/oauth)

JOB_ID=$(echo "$OAUTH_RESP" | jq -r '.job_id')
echo "OAuth job: $JOB_ID"
echo "Code: $(echo "$OAUTH_RESP" | jq -r '.user_code')"
```

**Step 2: Poll for completion**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/providers/anthropic/auth/oauth/$JOB_ID"
```

**Step 3: Set this as the default auth method**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/providers/anthropic/auth/default \
  -d '{
    "method": "oauth"
  }'
```

**Step 4: Add a second account to the pool**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  -X POST http://localhost:3000/api/v1/agent/providers/anthropic/auth/accounts
```

**Step 5: List accounts and verify**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/providers/anthropic/auth/accounts
```

### 3.5 Headless Autonomous Run with Job Monitoring

Running an autonomous agent loop without an interactive session.

**Step 1: Dispatch a headless run**

```
RUN_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/headless/runs \
  -d '{
    "prompt": "Run the full test suite, fix any failing tests, and summarize what was changed.",
    "format": "json"
  }')

JOB_ID=$(echo "$RUN_RESP" | jq -r '.job_id')
echo "Headless job: $JOB_ID"
```

**Step 2: Poll for completion**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/jobs/$JOB_ID
```

**Step 3: Retrieve the result**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/jobs/$JOB_ID/result
```

### 3.6 Skill Hub Discovery and Installation

**Step 1: Search the skill hub**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/skills/hub/search?q=database+migration"
```

**Step 2: Preview a skill before installing**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  "http://localhost:3000/api/v1/agent/skills/hub/preview?id=db-migration-helper"
```

**Step 3: Install the skill**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/hub/install \
  -d '{
    "id": "db-migration-helper"
  }'
```

**Step 4: Verify installation and trust**

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Hoody-Cwd: /home/user/project" \ \
  http://localhost:3000/api/v1/agent/skills
```

```
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/skills/trust \
  -d '{
    "root": "/home/user/.hoody/skills",
    "rel": "db-migration-helper",
    "trusted": true
  }'
```

### 3.7 Error Recovery: Stale Hook Nonce

When a hook mutation fails due to an expired nonce, re-request one.

```
# Step 1: Get a fresh nonce
NONCE_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X POST http://localhost:3000/api/v1/agent/hooks/begin-write \
  -d '{
    "session_id": "ses_new123",
    "op": "upsert"
  }')

NONCE=$(echo "$NONCE_RESP" | jq -r '.nonce')

# Step 2: Retry the hook mutation with the fresh nonce
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PUT http://localhost:3000/api/v1/agent/hooks \
  -d "{
    \"session_id\": \"ses_new123\",
    \"nonce\": \"$NONCE\",
    \"name\": \"post-deploy\",
    \"event\": \"turn_complete\",
    \"command\": \"notify-team.sh\",
    \"enabled\": true
  }"
```

### 3.8 Error Recovery: Stale CAS Revision on Todos

When a todo update fails due to a stale revision, fetch the current revision and retry.

```
# Step 1: Get current revision
REV_RESP=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ \
  http://localhost:3000/api/v1/agent/todos/revision)

REVISION=$(echo "$REV_RESP" | jq -r '.revision')

# Step 2: Retry the update with the current revision
curl -s -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \ \
  -X PATCH http://localhost:3000/api/v1/agent/todos/todo_abc123 \
  -d "{
    \"revision\": \"$REVISION\",
    \"state\": \"in-progress\"
  }"
```

---

## 4. Quick Reference

### Endpoint Groups Summary

| Group | Endpoint Count | Key Paths |
|-------|---------------|-----------|
| Sessions | 25 | `/sessions`, `/sessions/{id}/messages`, `/sessions/{id}/prompt:sync` |
| Agents | 13 | `/agents`, `/agents/{name}/source`, `/agents/{name}/model` |
| Tools | 7 | `/tools`, `/tools/{name}/run`, `/sessions/{id}/tools` |
| Workflows | 8 | `/workflows`, `/workflows/runs`, `/sessions/{id}/workflows/{name}/runs` |
| Skills | 14 | `/skills`, `/skills/hub/search`, `/skills/source` |
| Memory | 12 | `/memory/items`, `/memory/search`, `/memory/graph` |
| Hooks | 9 | `/hooks`, `/hooks/begin-write`, `/hooks/toggle` |
| Loops | 5 | `/sessions/{id}/loops`, `/sessions/{id}/loops/{loopId}/run-now` |
| Todos | 16 | `/todos`, `/todos/{id}/run`, `/todos/{id}/proposals/{pid}/approve` |
| Providers & Models | 18 | `/providers`, `/providers/{id}/auth`, `/models` |
| GitHub | 10 | `/github/clone`, `/github/commit`, `/github/pr` |
| Jobs | 3 | `/jobs/{id}`, `/jobs/{id}/result` |
| Headless | 1 | `/headless/runs` |
| Settings | 5 | `/settings`, `/settings/fusion` |
| ACP | 2 | `/acp/agents`, `/acp/agents/{agent}/secrets/{key}` |
| Logs | 5 | `/logs`, `/logs/stream`, `/logs/sources` |
| Statistics & Usage | 3 | `/statistics`, `/usage/by-model`, `/usage/by-account` |
| Tasks | 4 | `/sessions/{id}/tasks`, `/sessions/{id}/tasks/{tid}/cancel` |
| Discovery | 2 | `/realms`, `/containers` |
| System | 5 | `/health`, `/metrics`, `/openapi.json`, `/openapi.yaml`, `/docs` |

### Common Headers

| Header | Purpose |
|--------|---------|
| `Authorization: Bearer <token>` | Authentication (all endpoints except `/health`) |
| `X-Hoody-Cwd: <path>` | Working directory scope for the request |
| `X-Hoody-Config-Dir: <path>` | Configuration directory scope |
| `X-Hoody-Realm: <id>` | Realm selection (rejected by many cwd-scoped endpoints) |
| `X-Hoody-Gate-Policy: auto_approve` | Skip confirmation gates in automated flows |
| `Content-Type: application/json` | Required for all request bodies |

### Response Patterns

**Success with data:**
```
{
  "field": "value"
}
```

**List with pagination:**
```
{
  "items": [],
  "meta": { "total": 0, "page": 1, "limit": 50 }
}
```

**Async job dispatch:**
```
{
  "job_id": "job_xxx"
}
```

**CAS-guarded operations:**
```
{
  "revision": "rev_xxx"
}
```

### Essential Parameters

| Parameter | Type | Used By |
|-----------|------|---------|
| `session_id` | string (path) | Most session-scoped endpoints |
| `id` | string (path) | Jobs, sessions, memory items, todos |
| `name` | string (path) | Agents, workflows, tools |
| `project` | string (query) | Memory operations |
| `realm` | string (query) | Container listing |
| `scope` | string (query) | Statistics (`cwd` or `all`) |
| `since` | integer (query) | Usage endpoints (unix seconds) |
| `limit` | integer (query) | List pagination |
| `page` | integer (query) | List pagination |

### Workflow Endpoint Quick Map

| Action | Method + Path |
|--------|--------------|
| Run workflow on session | `POST /sessions/{id}/workflows/{name}/runs` |
| List all workflows | `GET /workflows` |
| Get workflow definition | `GET /workflows/{name}` |
| Create/replace workflow | `PUT /workflows/{name}` |
| Delete user workflow | `DELETE /workflows/{name}` |
| Hide system workflow | `POST /workflows/{name}/hide` |
| List workflow runs | `GET /workflows/runs` |
| Get workflow run | `GET /workflows/runs/{run_id}` |
| Cancel workflow run | `POST /workflows/runs/{run_id}/cancel` |
| Inject workflow feedback | `POST /sessions/{id}/workflow/messages` |

### Session Endpoint Quick Map

| Action | Method + Path |
|--------|--------------|
| List sessions | `GET /sessions` |
| Create session | `POST /sessions` |
| Get session | `GET /sessions/{id}` |
| Delete session | `DELETE /sessions/{id}` |
| Dispatch turn (async) | `POST /sessions/{id}/messages` |
| Dispatch prompt (sync) | `POST /sessions/{id}/prompt:sync` |
| Dispatch prompt (stream) | `POST /sessions/{id}/prompt:stream` |
| Stream events | `GET /sessions/{id}/stream` |
| Replay events | `GET /sessions/{id}/replay` |
| Confirm gate | `POST /sessions/{id}/confirm` |
| Answer question | `POST /sessions/{id}/answer` |
| Cancel turn | `POST /sessions/{id}/cancel` |
| Close session | `POST /sessions/{id}/close` |
| Switch agent | `PATCH /sessions/{id}/agent` |
| Switch model | `PATCH /sessions/{id}/model` |
| Change effort | `PATCH /sessions/{id}/effort` |
| Change verbosity | `PATCH /sessions/{id}/verbosity` |
| Trim history | `POST /sessions/{id}/trim` |
| Run tool in session | `POST /sessions/{id}/tools/{name}/run` |
| List session tools | `GET /sessions/{id}/tools` |

### Todo Endpoint Quick Map

| Action | Method + Path |
|--------|--------------|
| List todos | `GET /todos` |
| Create todo | `POST /todos` |
| Get todo | `GET /todos/{id}` |
| Update todo (CAS) | `PATCH /todos/{id}` |
| Claim todo | `POST /todos/{id}/claim` |
| Release todo | `POST /todos/{id}/release` |
| Run todo autonomously | `POST /todos/{id}/run` |
| Approve proposal | `POST /todos/{id}/proposals/{pid}/approve` |
| Deny proposal | `POST /todos/{id}/proposals/{pid}/deny` |
| Post comment + orchestrator | `POST /todos/{id}/message` |
| Post comment only | `POST /todos/{id}/messages` |
| Snooze todo | `POST /todos/{id}/snooze` |
| Archive todo | `POST /todos/{id}/archive` |
| Cancel orchestrator run | `POST /todos/{id}/cancel-run` |
| Triage all todos | `POST /todos/triage` |
| Purge archived | `POST /todos/purge` |