<!--
hoody-agent Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T19:44:02.812Z
Model: mimo-v2.5-pro + fixer:z-ai/glm-5.1
Mode: http


Tokens: 97799

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

# hoody-agent Subskill

## Table of Contents

- [Overview](#overview)
- [Core Resource Workflows](#core-resource-workflows)
- [Advanced Operations](#advanced-operations)
- [Quick Reference](#quick-reference)

---

## Overview

### What is hoody-agent?

hoody-agent is the AI agent orchestration and task execution service within the Hoody ecosystem. It provides a comprehensive API for managing workspaces, sessions, branches, configuration, files, memory, MCP (Model Context Protocol) servers, MITM (Man-in-the-Middle) rules, orchestration workflows, permissions, providers, questions, skills, tools, and more.

The service acts as the central nervous system for AI agent interactions — from simple prompt-response sessions to complex multi-phase orchestration workflows with budgets, verifiers, and background workers.

### When to Use hoody-agent

Use hoody-agent when you need to:

- **Interact with AI agents**: Send prompts, receive responses, manage conversation sessions
- **Manage workspaces**: Create, update, delete, and configure workspaces (projects)
- **Orchestrate complex tasks**: Use phases, todo entries, budgets, and executors for multi-step workflows
- **Manage configuration**: Configure AI providers, reviewers, verifiers, CLI agents, and tool overrides
- **Work with files**: Search, read, and manage files within workspaces
- **Manage memory**: Create memory blocks, journal entries, and track memory history
- **Configure MCP servers**: Add, authenticate, and manage Model Context Protocol servers
- **Manage MITM rules**: Create, test, and monitor Man-in-the-Middle rules for tool interception
- **Handle permissions and questions**: Approve or deny permission requests, answer or reject questions from AI assistants
- **Manage providers**: Configure and authenticate AI providers (OpenAI, Anthropic, etc.)
- **Manage skills**: Create, update, and delete skills for AI agents
- **Use experimental features**: Access experimental tools and resources

### Authentication

All hoody-agent endpoints (except the health check) require Bearer token authentication. Include the token in the `Authorization` header:

```
Authorization: Bearer $HOODY_TOKEN
```

### Base URL and Path Rules

- **Base URL**: `https://api.hoody.icu`
- **Server base path**: `/api/v1/agent` (from OpenAPI `servers` configuration)
- **Full URL pattern**: `https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/...`

The endpoint paths listed in this document start after the server base path. To construct the full URL, prepend `https://api.hoody.icu/api/v1/agent` to any endpoint path. For example, `GET /api/v1/workspaces/health` becomes `https://api.hoody.icu/api/v1/agent/workspaces/health`.

### Service Philosophy

hoody-agent embodies the Hoody philosophy of AI agent orchestration and task execution. It provides a unified interface for managing all aspects of AI agent interactions, scaling from single-turn prompts to fully automated, multi-step pipelines.

---

## Core Resource Workflows

### 2.1 Health Check

The health check endpoint provides a standardized health response. It is unauthenticated and can be used to verify the service is running.

**Endpoints:**
- `GET /api/v1/workspaces/health` — Returns health status

**Example:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/health"
```

**Notes:**
- This endpoint is unauthenticated
- Returns a standardized health response
- Use to verify service availability before making authenticated requests

---

### 2.2 Workspaces

Workspaces (also called projects) are the top-level organizational unit in hoody-agent. Each workspace contains sessions, branches, configuration, files, memory, and other resources.

**Endpoints:**
- `GET /api/v1/workspaces` — List all workspaces (paginated)
- `POST /api/v1/workspaces` — Create a new workspace
- `GET /api/v1/workspaces/{workspaceID}` — Get workspace details
- `PATCH /api/v1/workspaces/{workspaceID}` — Update workspace properties
- `DELETE /api/v1/workspaces/{workspaceID}` — Delete a workspace
- `POST /api/v1/workspaces/{workspaceID}/container` — Set container binding
- `DELETE /api/v1/workspaces/{workspaceID}/container` — Remove container binding

**List Workspaces:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Workspace:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "my-project",
    "icon": "📁"
  }'
```

**Get Workspace:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Workspace:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "updated-project-name",
    "icon": "🚀"
  }'
```

**Delete Workspace:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Set Container Binding:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/container" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "containerId": "container-123"
  }'
```

**Remove Container Binding:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/container" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Workspaces are the top-level organizational unit
- Each workspace has a unique `workspaceID`
- Container binding links a workspace to a running container instance
- Use `GET /api/v1/workspaces` to list all workspaces with pagination

---

### 2.3 Sessions

Sessions are conversation threads within a workspace. Each session maintains its own message history, configuration, and state.

#### 2.3.1 Core Session CRUD

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/sessions` — List sessions (paginated, newest-first)
- `POST /api/v1/workspaces/{workspaceID}/sessions` — Create a new session
- `GET /api/v1/workspaces/{workspaceID}/sessions/status` — Get status of all sessions
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}` — Get session details
- `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}` — Update session properties
- `DELETE /api/v1/workspaces/{workspaceID}/sessions/{sessionID}` — Delete session (irreversible)
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/children` — Get forked child sessions
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/permissions` — Get merged permission ruleset
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/summary` — Get lightweight summary
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/diff` — Get file changes (diffs)
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/todo` — Get session todo list

**List Sessions:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "permission": [
      {
        "permission": "read",
        "pattern": "*",
        "action": "allow"
      }
    ]
  }'
```

**Get Session Statuses:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Session:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Session:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "title": "Updated Session Title",
    "permission": [
      {
        "permission": "write",
        "pattern": "*.js",
        "action": "allow"
      }
    ]
  }'
```

**Delete Session:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Child Sessions:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/children" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Session Permissions:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/permissions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Session Summary:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/summary" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Session Diff:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/diff" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Session Todo:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/todo" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Sessions are conversation threads within a workspace
- Each session has a unique `sessionID`
- Sessions can be forked to create child sessions
- The `permission` field is a session-scoped ruleset merged on top of `config.permission`
- Deleting a session is irreversible

---

#### 2.3.2 Messages & Prompts

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/messages` — List messages (chronological, cursor-based pagination)
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}` — Get specific message
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}/stream` — SSE stream of message updates
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}/tools/{callID}` — Get specific tool call
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message` — Send message (streams AI response)
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/prompt_async` — Send message asynchronously
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/command` — Send command for execution
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/shell` — Execute shell command
- `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message/{messageID}` — Update mutable fields on user message
- `DELETE /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message/{messageID}/part/{partID}` — Delete message part
- `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/message/{messageID}/part/{partID}` — Update message part

**List Messages:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/messages" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Message:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Stream Message Updates:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Tool Call:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}/tools/{callID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Send Message (Streaming):**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "model": {
      "providerID": "openai",
      "modelID": "gpt-4"
    },
    "parts": [
      {
        "type": "text",
        "text": "Hello, can you help me with this code?",
        "time": {
          "start": 1704067200000
        },
        "mime": "text/plain",
        "url": "file:///src/main.ts",
        "source": {
          "text": {
            "value": "function main() { ... }",
            "start": 0,
            "end": 100
          },
          "type": "file",
          "path": "/src/main.ts",
          "range": {
            "start": {
              "line": 1,
              "character": 0
            },
            "end": {
              "line": 10,
              "character": 0
            }
          },
          "name": "main.ts",
          "kind": 1,
          "clientName": "hoody-agent",
          "uri": "file:///src/main.ts",
          "value": "function main() { ... }",
          "start": 0,
          "end": 100
        },
        "name": "main-function",
        "prompt": "Explain this function",
        "description": "The main entry point",
        "agent": "default",
        "model": {
          "providerID": "openai",
          "modelID": "gpt-4"
        }
      }
    ]
  }'
```

**Send Message (Async):**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/prompt_async" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "model": {
      "providerID": "openai",
      "modelID": "gpt-4"
    },
    "parts": [
      {
        "type": "text",
        "text": "Analyze this codebase and suggest improvements.",
        "time": {
          "start": 1704067200000
        },
        "mime": "text/plain",
        "url": "file:///src/main.ts",
        "source": {
          "text": {
            "value": "function main() { ... }",
            "start": 0,
            "end": 100
          },
          "type": "file",
          "path": "/src/main.ts",
          "range": {
            "start": {
              "line": 1,
              "character": 0
            },
            "end": {
              "line": 10,
              "character": 0
            }
          },
          "name": "main.ts",
          "kind": 1,
          "clientName": "hoody-agent",
          "uri": "file:///src/main.ts",
          "value": "function main() { ... }",
          "start": 0,
          "end": 100
        },
        "name": "analysis-request",
        "prompt": "Analyze and suggest improvements",
        "description": "Codebase analysis request",
        "agent": "default",
        "model": {
          "providerID": "openai",
          "modelID": "gpt-4"
        }
      }
    ]
  }'
```

**Send Command:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/command" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "command": "explain",
    "arguments": "the main function",
    "parts": [
      {
        "type": "text",
        "mime": "text/plain",
        "url": "file:///src/main.ts",
        "source": {
          "text": {
            "value": "function main() { ... }",
            "start": 0,
            "end": 100
          },
          "type": "file",
          "path": "/src/main.ts",
          "range": {
            "start": {
              "line": 1,
              "character": 0
            },
            "end": {
              "line": 10,
              "character": 0
            }
          },
          "name": "main.ts",
          "kind": 1,
          "clientName": "hoody-agent",
          "uri": "file:///src/main.ts"
        }
      }
    ]
  }'
```

**Execute Shell Command:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/shell" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "agent": "default",
    "model": {
      "providerID": "openai",
      "modelID": "gpt-4"
    },
    "command": "ls -la"
  }'
```

**Notes:**
- Messages are returned in chronological order (oldest first)
- Use `after` cursor param for efficient incremental fetching
- The `/message` endpoint streams the AI response via SSE
- The `/prompt_async` endpoint returns immediately and processes in background
- The `/command` endpoint sends a command for execution by the AI assistant
- The `/shell` endpoint executes a shell command within the session context

---

#### 2.3.3 Session Actions

**Endpoints:**
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/abort` — Abort in-progress AI processing
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/fork` — Fork session at specific message
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/revert` — Revert to specific message
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/unrevert` — Restore reverted messages
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/init` — Trigger AI-based workspace analysis
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/export` — Export session
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/summarize` — Generate AI summary
- `PATCH /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/tags` — Update MITM tags

**Abort Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/abort" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Fork Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/fork" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "messageID": "msg-123"
  }'
```

**Revert Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/revert" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "messageID": "msg-456"
  }'
```

**Unrevert Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/unrevert" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Init Session (AI Analysis):**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/init" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "modelID": "gpt-4",
    "providerID": "openai",
    "messageID": "msg-789"
  }'
```

**Export Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "format": "markdown"
  }'
```

**Summarize Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/summarize" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "providerID": "openai",
    "modelID": "gpt-4"
  }'
```

**Update Session Tags:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "add": ["tag1", "tag2"],
    "remove": ["old-tag"]
  }'
```

**Notes:**
- `abort` stops any in-progress AI processing
- `fork` creates a new session forked at a specific message point
- `revert` undoes changes after a specific message
- `unrevert` restores all previously reverted messages
- `init` triggers AI-based workspace analysis to generate AGENTS.md
- `export` supports Markdown, JSON, or Plain Text formats
- `summarize` uses AI compaction to preserve key information

---

#### 2.3.4 Session Jobs

Background jobs are created for RSI, self-tuning, CLI agent, bash, and webfetch operations.

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs` — List background jobs
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}` — Get job details
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/output` — Get full job output
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/cancel` — Cancel a job
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs/cancel` — Bulk cancel jobs
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/retry` — Retry a failed job
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/jobs/inject` — Inject job summaries into session

**List Jobs:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs?status=active" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Job:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Job Output:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/output" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Cancel Job:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/cancel" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Bulk Cancel Jobs:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "jobIds": ["job-1", "job-2", "job-3"]
  }'
```

**Retry Job:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/retry" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Inject Job Summaries:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/inject" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "jobIds": ["job-1", "job-2"]
  }'
```

**Notes:**
- Jobs can be filtered by status: `active`, `completed`, `all`
- Use `limit` and `cursor` for pagination
- Only `failed`, `expired`, and `cancelled` jobs are eligible for retry
- `inject` attaches job summary parts to the last user message

---

#### 2.3.5 CLI Agent, RSI & Self-Tuning

**Endpoints:**
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/cli-agent` — Run external CLI agent
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/cli-agent/runs/{jobID}/stream` — SSE stream for CLI agent job
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/rsi/review` — Run RSI review
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/rsi/runs/{jobID}/stream` — SSE stream for RSI job
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/self-tuning/tune` — Run self-tuning loop
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/self-tuning/amplify` — Run amplify loop
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/self-tuning/runs/{jobID}/stream` — SSE stream for self-tuning job

**Run CLI Agent:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/cli-agent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "agent": "gemini",
    "prompt": "Analyze this codebase"
  }'
```

**Stream CLI Agent Progress:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/cli-agent/runs/{jobID}/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Run RSI Review:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/rsi/review" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Stream RSI Progress:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/rsi/runs/{jobID}/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Run Self-Tuning:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/self-tuning/tune" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Run Amplify:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/self-tuning/amplify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "n": 5
  }'
```

**Stream Self-Tuning Progress:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/self-tuning/runs/{jobID}/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- CLI agents include gemini, codex, claude
- RSI (Reviewer-Selected-Improvement) fans out review to configured reviewer models
- Self-tuning runs against the session's verifier
- Amplify uses best-of-N with majority voting (n must be odd, max 11)
- All return a queued jobID; subscribe to the stream endpoint for progress

---

#### 2.3.6 Session Loop

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/loop` — Get active loop directive
- `POST /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/loop` — Install loop directive
- `DELETE /api/v1/workspaces/{workspaceID}/sessions/{sessionID}/loop` — Clear loop directive

**Get Loop:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/loop" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Install Loop:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/loop" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "prompt": "Continue improving the code",
    "iters": 5
  }'
```

**Clear Loop:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/loop" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Loop directives make the session re-enter its prompt loop for `iters` iterations
- The same `prompt` is synthesized as the user turn each iteration
- Clearing the loop also cancels the running prompt

---

#### 2.3.7 Sessions Live View

**Endpoints:**
- `GET /api/v1/agent/sessions/live` — HTML page showing live agent sessions
- `GET /api/v1/agent/all` — Alias for sessions/live

**View Live Sessions:**

```
curl -s "https://api.hoody.icu/api/v1/agent/agent/sessions/live" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Returns an HTML page designed for iframe embedding
- Shows live agent sessions across all workspaces
- `/all` is an alias for `/sessions/live`

---

### 2.4 Branches

Branches are isolated git worktrees with their own directory, status, and disk usage.

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/branches` — List all branches
- `POST /api/v1/workspaces/{workspaceID}/branches` — Create a new branch
- `DELETE /api/v1/workspaces/{workspaceID}/branches/{id}` — Delete a branch
- `PATCH /api/v1/workspaces/{workspaceID}/branches/{id}` — Update branch properties
- `GET /api/v1/workspaces/{workspaceID}/branches/{id}/diff` — Get branch diff
- `POST /api/v1/workspaces/{workspaceID}/branches/{id}/merge` — Merge branch
- `GET /api/v1/workspaces/{workspaceID}/branches/{id}/pr` — Get pull request info
- `POST /api/v1/workspaces/{workspaceID}/branches/{id}/pr` — Create pull request
- `POST /api/v1/workspaces/{workspaceID}/branches/{id}/pull` — Pull from remote
- `POST /api/v1/workspaces/{workspaceID}/branches/{id}/push` — Push to remote
- `GET /api/v1/workspaces/{workspaceID}/branches/{id}/remote-status` — Get remote status
- `POST /api/v1/workspaces/{workspaceID}/branches/{id}/reset` — Reset branch
- `POST /api/v1/workspaces/{workspaceID}/branches/{id}/retry` — Retry branch operation
- `GET /api/v1/workspaces/{workspaceID}/branches/{id}/status` — Get branch status
- `GET /api/v1/workspaces/{workspaceID}/branches/disk-usage` — Get disk usage
- `GET /api/v1/workspaces/{workspaceID}/branches/remote` — List remote branches
- `GET /api/v1/workspaces/{workspaceID}/branches/remote-refs` — Get remote refs

**List Branches:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Branch:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "feature/new-feature"
  }'
```

**Delete Branch:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Branch:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "renamed-branch"
  }'
```

**Get Branch Diff:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/diff" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Merge Branch:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/merge" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Pull Request:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/pr" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Pull Request:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/pr" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "title": "New Feature",
    "description": "Implements the new feature"
  }'
```

**Pull from Remote:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/pull" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Push to Remote:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/push" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Remote Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/remote-status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Reset Branch:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/reset" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Retry Branch Operation:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/retry" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Branch Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/{id}/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Disk Usage:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/disk-usage" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Remote Branches:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/remote" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Remote Refs:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/branches/remote-refs?remote=origin" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Each branch is an isolated git worktree
- Branches have their own directory, status, and disk usage
- Use `remote` query parameter to select which remote to inspect
- The list is bounded by the project's branch count

---

### 2.5 Configuration

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/config` — Get configuration
- `PATCH /api/v1/workspaces/{workspaceID}/config` — Update configuration
- `GET /api/v1/workspaces/{workspaceID}/config/cli-agents` — Get CLI agent config
- `GET /api/v1/workspaces/{workspaceID}/config/permission` — Get permission config
- `GET /api/v1/workspaces/{workspaceID}/config/providers` — Get provider config
- `GET /api/v1/workspaces/{workspaceID}/config/reviewers` — Get reviewer config
- `GET /api/v1/workspaces/{workspaceID}/config/tool-overrides` — Get tool overrides
- `GET /api/v1/workspaces/{workspaceID}/config/verifiers` — Get verifier config

**Get Configuration:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Configuration:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "defaultProvider": "openai",
    "defaultModel": "gpt-4"
  }'
```

**Get CLI Agents:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config/cli-agents" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Permission Config:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config/permission" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Providers:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config/providers" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Reviewers:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config/reviewers" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Tool Overrides:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config/tool-overrides" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Verifiers:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/config/verifiers" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Configuration is workspace-scoped
- `config/permission` returns permission and yolo overrides from workspace config only
- `config/tool-overrides` returns tool_overrides from workspace config only
- Reviewers and verifiers are used for RSI and self-tuning

---

### 2.6 Files

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/files/file` — List files and directories
- `GET /api/v1/workspaces/{workspaceID}/files/file/content` — Read file content
- `GET /api/v1/workspaces/{workspaceID}/files/file/status` — Get git status
- `GET /api/v1/workspaces/{workspaceID}/files/find` — Search text patterns (ripgrep)
- `GET /api/v1/workspaces/{workspaceID}/files/find/file` — Search files by name
- `GET /api/v1/workspaces/{workspaceID}/files/find/symbol` — Search symbols (LSP)

**List Files:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/files/file?path=/src" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Read File Content:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/files/file/content?path=/src/main.ts" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Git Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/files/file/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Search Text Patterns:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/files/find?pattern=function+main" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Search Files by Name:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/files/find/file?pattern=*.ts" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Search Symbols:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/files/find/symbol?query=main" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- `files/find` uses ripgrep for text pattern search
- `files/find/file` searches for files or directories by name or pattern
- `files/find/symbol` uses LSP for symbol search (functions, classes, variables)
- `files/file/status` returns git status of all files

---

### 2.7 Memory

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/memory/blocks` — List memory blocks
- `GET /api/v1/workspaces/{workspaceID}/memory/blocks/{label}` — Get memory block
- `PUT /api/v1/workspaces/{workspaceID}/memory/blocks/{label}` — Create/overwrite memory block
- `PATCH /api/v1/workspaces/{workspaceID}/memory/blocks/{label}` — Update memory block substring
- `DELETE /api/v1/workspaces/{workspaceID}/memory/blocks/{label}` — Delete memory block
- `GET /api/v1/workspaces/{workspaceID}/memory/config` — Get memory config
- `GET /api/v1/workspaces/{workspaceID}/memory/history` — List memory history
- `GET /api/v1/workspaces/{workspaceID}/memory/history/{id}` — Get history event
- `GET /api/v1/workspaces/{workspaceID}/memory/journal` — List journal entries
- `POST /api/v1/workspaces/{workspaceID}/memory/journal` — Create journal entry
- `DELETE /api/v1/workspaces/{workspaceID}/memory/journal/{id}` — Delete journal entry
- `GET /api/v1/workspaces/{workspaceID}/memory/journal/{id}` — Get journal entry
- `GET /api/v1/workspaces/{workspaceID}/memory/journal/count` — Count journal entries
- `POST /api/v1/workspaces/{workspaceID}/memory/journal/search` — Search journal entries

**List Memory Blocks:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks?scope=workspace" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Memory Block:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks/{label}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create/Overwrite Memory Block:**

```
curl -s -X PUT "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks/{label}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "content": "This is the memory block content."
  }'
```

**Update Memory Block Substring:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks/{label}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "old": "old text",
    "new": "new text"
  }'
```

**Delete Memory Block:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks/{label}?scope=workspace" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Memory Config:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/config" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Memory History:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/history" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get History Event:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/history/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Journal Entries:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Journal Entry:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "content": "Journal entry content",
    "tags": ["important", "decision"]
  }'
```

**Delete Journal Entry:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Journal Entry:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Count Journal Entries:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal/count" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Search Journal Entries:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "query": "important decision",
    "tags": ["decision"]
  }'
```

**Notes:**
- Memory blocks can be scoped to `global` or `workspace`
- Always pass `?scope=global` or `?scope=workspace` when deleting
- Journal entries support text search and tag filtering
- History tracks all memory changes with cursor-based pagination

---

### 2.8 MCP (Model Context Protocol)

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/mcp` — List MCP servers
- `POST /api/v1/workspaces/{workspaceID}/mcp` — Add MCP server
- `DELETE /api/v1/workspaces/{workspaceID}/mcp/{name}/auth` — Remove OAuth credentials
- `POST /api/v1/workspaces/{workspaceID}/mcp/{name}/auth` — Start OAuth flow
- `POST /api/v1/workspaces/{workspaceID}/mcp/{name}/auth/authenticate` — Start OAuth and wait for callback
- `POST /api/v1/workspaces/{workspaceID}/mcp/{name}/auth/callback` — Complete OAuth callback
- `POST /api/v1/workspaces/{workspaceID}/mcp/{name}/connect` — Connect to MCP server
- `POST /api/v1/workspaces/{workspaceID}/mcp/{name}/disconnect` — Disconnect from MCP server

**List MCP Servers:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Add MCP Server:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "my-mcp-server",
    "url": "https://mcp-server.example.com"
  }'
```

**Start OAuth Flow:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/{name}/auth" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Remove OAuth Credentials:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/{name}/auth" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Authenticate (Start + Wait):**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/{name}/auth/authenticate" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Complete OAuth Callback:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/{name}/auth/callback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "code": "auth-code-from-provider"
  }'
```

**Connect to MCP Server:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/{name}/connect" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Disconnect from MCP Server:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/{name}/disconnect" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- MCP servers provide tools and resources to AI agents
- OAuth flow: start → user authorizes → callback completes
- `authenticate` combines start + wait for callback (opens browser)
- Connect/disconnect manage the active connection state

---

### 2.9 MITM (Man-in-the-Middle)

MITM rules intercept and modify tool calls made by AI agents.

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/mitm/cooldowns` — Get cooldown status
- `POST /api/v1/workspaces/{workspaceID}/mitm/diagnostics/dry-run` — Test rules against synthetic event
- `POST /api/v1/workspaces/{workspaceID}/mitm/diagnostics/match-trace` — Detailed match trace
- `GET /api/v1/workspaces/{workspaceID}/mitm/events` — Subscribe to rule-fired events
- `GET /api/v1/workspaces/{workspaceID}/mitm/logs` — Get MITM logs
- `GET /api/v1/workspaces/{workspaceID}/mitm/logs/{id}` — Get specific log entry
- `POST /api/v1/workspaces/{workspaceID}/mitm/overlay/rebase` — Rebase overlay rules
- `POST /api/v1/workspaces/{workspaceID}/mitm/overlay/reset` — Reset overlay
- `GET /api/v1/workspaces/{workspaceID}/mitm/plugin-descriptors` — Get plugin metadata
- `GET /api/v1/workspaces/{workspaceID}/mitm/rules` — List effective rules
- `POST /api/v1/workspaces/{workspaceID}/mitm/rules` — Create rule
- `DELETE /api/v1/workspaces/{workspaceID}/mitm/rules/{id}` — Delete rule
- `PATCH /api/v1/workspaces/{workspaceID}/mitm/rules/{id}` — Patch rule
- `PUT /api/v1/workspaces/{workspaceID}/mitm/rules/{id}` — Replace rule
- `POST /api/v1/workspaces/{workspaceID}/mitm/rules/{id}/enable` — Toggle rule enabled
- `POST /api/v1/workspaces/{workspaceID}/mitm/rules/{id}/transient-enable` — Transient toggle
- `PATCH /api/v1/workspaces/{workspaceID}/mitm/sessions/{sessionID}/tags` — Update session tags
- `GET /api/v1/workspaces/{workspaceID}/mitm/snapshot` — Get effective state snapshot
- `GET /api/v1/workspaces/{workspaceID}/mitm/tags` — List tags
- `POST /api/v1/workspaces/{workspaceID}/mitm/tags` — Create tag
- `DELETE /api/v1/workspaces/{workspaceID}/mitm/tags/{id}` — Delete tag
- `GET /api/v1/workspaces/{workspaceID}/mitm/validation-rules` — Get validation rules
- `POST /api/v1/workspaces/{workspaceID}/mitm/webhooks/verify` — Verify webhook

**Get Snapshot:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/snapshot" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Rules:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Rule:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "block-dangerous-commands",
    "toolName": "shell",
    "contentMatch": "rm -rf",
    "action": "block"
  }'
```

**Delete Rule:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Patch Rule:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "enabled": true
  }'
```

**Replace Rule:**

```
curl -s -X PUT "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "updated-rule",
    "toolName": "shell",
    "action": "allow"
  }'
```

**Toggle Rule Enabled:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules/{id}/enable" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Transient Toggle:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules/{id}/transient-enable" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Dry Run:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/diagnostics/dry-run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "toolName": "shell",
    "content": "rm -rf /tmp/test"
  }'
```

**Match Trace:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/diagnostics/match-trace" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "toolName": "shell",
    "content": "rm -rf /tmp/test"
  }'
```

**Get Logs:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/logs" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Log Entry:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/logs/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Subscribe to Events:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/events" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Cooldowns:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/cooldowns" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Plugin Descriptors:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/plugin-descriptors" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Validation Rules:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/validation-rules" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Verify Webhook:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/webhooks/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "url": "https://webhook.example.com/hook",
    "auth": "Bearer webhook-token"
  }'
```

**List Tags:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/tags" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Tag:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "production"
  }'
```

**Delete Tag:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/tags/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Session Tags:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/sessions/{sessionID}/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "add": ["tag1"],
    "remove": ["tag2"]
  }'
```

**Reset Overlay:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/overlay/reset" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Rebase Overlay:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/overlay/rebase" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- MITM rules intercept tool calls made by AI agents
- Rules can be enabled/disabled permanently or transiently
- Overlay rules are layered on top of base config
- `dry-run` tests rules without executing actions
- `match-trace` shows why each rule did or did not match
- Transient enables do not persist across restarts

---

### 2.10 Orchestration

Orchestration manages complex multi-step workflows with phases, todo entries, budgets, and executors.

#### 2.10.1 Phases

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/orchestration/phases` — List phases
- `POST /api/v1/workspaces/{workspaceID}/orchestration/phases` — Create phase
- `DELETE /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}` — Delete phase
- `GET /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}` — Get phase
- `POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/entries` — Add entries to phase
- `DELETE /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory` — Delete phase memory
- `GET /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory` — Get phase memory
- `POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory` — Create phase memory
- `POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/review` — Review phase
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/rounds` — Update rounds
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/status` — Update status
- `GET /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/summary` — Get phase summary
- `POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/verify` — Verify phase
- `GET /api/v1/workspaces/{workspaceID}/orchestration/phases/memory` — List all phase memory

**List Phases:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Phase:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "Phase 1: Setup",
    "description": "Initial setup and configuration"
  }'
```

**Get Phase:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Delete Phase:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Add Entries to Phase:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/entries" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "entries": ["entry-1", "entry-2"]
  }'
```

**Get Phase Memory:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Phase Memory:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "content": "Important decision: use TypeScript for all new code"
  }'
```

**Delete Phase Memory:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Review Phase:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/review" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Rounds:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/rounds" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "rounds": 5
  }'
```

**Update Status:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "status": "active"
  }'
```

**Get Phase Summary:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/summary" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Verify Phase:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/verify" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List All Phase Memory:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/memory" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Phases group related entries into sequential execution units
- Each phase has its own rounds budget, memory notes, and orchestrator session
- Memory notes are carried across rounds and sessions

---

#### 2.10.2 Todo

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/orchestration/todo` — List todo entries
- `POST /api/v1/workspaces/{workspaceID}/orchestration/todo/entries` — Create todo entry
- `DELETE /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}` — Delete todo entry
- `GET /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}` — Get todo entry
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/priority` — Update priority
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/rounds` — Update rounds
- `GET /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/spec` — Get entry spec
- `PUT /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/spec` — Update entry spec
- `POST /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/spec/freeze` — Freeze entry spec
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/status` — Update status
- `GET /api/v1/workspaces/{workspaceID}/orchestration/todo/events` — Subscribe to todo events

**List Todo Entries:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Todo Entry:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "title": "Implement user authentication",
    "description": "Add OAuth2 authentication flow",
    "priority": 1
  }'
```

**Get Todo Entry:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Delete Todo Entry:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Priority:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/priority" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "priority": 2
  }'
```

**Update Rounds:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/rounds" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "rounds": 3
  }'
```

**Get Entry Spec:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/spec" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Entry Spec:**

```
curl -s -X PUT "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/spec" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "spec": "Detailed specification for the task"
  }'
```

**Freeze Entry Spec:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/spec/freeze" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Status:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries/{entryID}/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "status": "in_progress"
  }'
```

**Subscribe to Todo Events:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/events" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Todo entries are tasks within the orchestration workflow
- Each entry has a spec, priority, rounds, and status
- Freezing a spec prevents further modifications

---

#### 2.10.3 Budget

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/orchestration/budget` — Get budget
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/budget` — Update budget
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/budget/entries/{entryID}` — Update entry budget
- `POST /api/v1/workspaces/{workspaceID}/orchestration/budget/entries/{entryID}/lock` — Lock entry budget

**Get Budget:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/budget" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Budget:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/budget" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "totalTokens": 1000000,
    "totalCost": 100.00
  }'
```

**Update Entry Budget:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/budget/entries/{entryID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "tokens": 50000,
    "cost": 5.00
  }'
```

**Lock Entry Budget:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/budget/entries/{entryID}/lock" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Budget controls token and cost limits for orchestration
- Entry budgets can be locked to prevent further spending

---

#### 2.10.4 Executor

**Endpoints:**
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/entries/{entryID}/reverify` — Reverify entry
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/force-dispatch` — Force dispatch
- `GET /api/v1/workspaces/{workspaceID}/orchestration/executor/locks` — Get locks
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/pause` — Pause executor
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/resume` — Resume executor
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/start` — Start executor
- `GET /api/v1/workspaces/{workspaceID}/orchestration/executor/status` — Get executor status
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/stop-all` — Stop all workers
- `GET /api/v1/workspaces/{workspaceID}/orchestration/executor/workers` — List workers
- `POST /api/v1/workspaces/{workspaceID}/orchestration/executor/workers/{sessionID}/stop` — Stop worker

**Start Executor:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/start" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Executor Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Pause Executor:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/pause" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Resume Executor:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/resume" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Stop All Workers:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/stop-all" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Workers:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/workers" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Stop Worker:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/workers/{sessionID}/stop" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Locks:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/locks" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Force Dispatch:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/force-dispatch" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Reverify Entry:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/entries/{entryID}/reverify" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- The executor manages worker sessions that process todo entries
- Workers can be started, paused, resumed, and stopped
- `reverify` resets rounds_completed and triggers verification
- `force-dispatch` manually dispatches an entry

---

#### 2.10.5 Orchestrator

**Endpoints:**
- `POST /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/phases/{phaseID}/prompt` — Send prompt to phase
- `GET /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/phases/{phaseID}/session` — Get phase session
- `POST /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/prompt` — Send prompt to orchestrator
- `GET /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/session` — Get orchestrator session
- `POST /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/session` — Create orchestrator session
- `GET /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/sessions` — List orchestrator sessions

**List Orchestrator Sessions:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/orchestrator/sessions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Orchestrator Session:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/orchestrator/session" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create Orchestrator Session:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/orchestrator/session" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Send Prompt to Orchestrator:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/orchestrator/prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "prompt": "Plan the next phase of development"
  }'
```

**Get Phase Session:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/orchestrator/phases/{phaseID}/session" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Send Prompt to Phase:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/orchestrator/phases/{phaseID}/prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "prompt": "Begin implementing the authentication module"
  }'
```

**Notes:**
- The orchestrator manages the top-level planning session
- Each phase has its own orchestrator session
- Use the orchestrator to send high-level prompts and plans

---

#### 2.10.6 Orchestration Questions

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/orchestration/questions` — List unanswered questions
- `GET /api/v1/workspaces/{workspaceID}/orchestration/questions/{questionID}` — Get question
- `POST /api/v1/workspaces/{workspaceID}/orchestration/questions/{questionID}/answer` — Answer question

**List Questions:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/questions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Question:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/questions/{questionID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Answer Question:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/questions/{questionID}/answer" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "answer": "Use PostgreSQL for the database"
  }'
```

**Notes:**
- Questions are interactive prompts emitted by agents
- They need a human decision before the agent can continue
- Questions can be about approvals, clarifications, or decisions

---

#### 2.10.7 Import, Vault & Logging

**Endpoints:**
- `POST /api/v1/workspaces/{workspaceID}/orchestration/import` — Import orchestration
- `GET /api/v1/workspaces/{workspaceID}/orchestration/import/{jobID}` — Get import job status
- `GET /api/v1/workspaces/{workspaceID}/orchestration/log` — Get orchestration log
- `GET /api/v1/workspaces/{workspaceID}/orchestration/log/stream` — Stream orchestration log
- `POST /api/v1/workspaces/{workspaceID}/orchestration/purge` — Purge orchestration data
- `GET /api/v1/workspaces/{workspaceID}/orchestration/vault/discover` — Discover vault
- `POST /api/v1/workspaces/{workspaceID}/orchestration/vault/import` — Import from vault
- `POST /api/v1/workspaces/{workspaceID}/orchestration/vault/sync` — Sync vault
- `GET /api/v1/workspaces/{workspaceID}/orchestration/config` — Get orchestration config
- `PATCH /api/v1/workspaces/{workspaceID}/orchestration/config` — Update orchestration config
- `GET /api/v1/workspaces/{workspaceID}/orchestration/debug-dump` — Get debug dump
- `GET /api/v1/workspaces/{workspaceID}/orchestration/events` — Subscribe to events
- `GET /api/v1/workspaces/{workspaceID}/orchestration/events/connections` — Get event connections

**Import Orchestration:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/import" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "source": "https://example.com/orchestration.json"
  }'
```

**Get Import Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/import/{jobID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Orchestration Log:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/log" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Stream Orchestration Log:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/log/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Purge Orchestration:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/purge" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Discover Vault:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/vault/discover" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Import from Vault:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/vault/import" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "vaultId": "vault-123"
  }'
```

**Sync Vault:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/vault/sync" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Orchestration Config:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/config" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Orchestration Config:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "maxWorkers": 5,
    "autoStart": true
  }'
```

**Get Debug Dump:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/debug-dump" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Subscribe to Events:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/events" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Event Connections:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/events/connections" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- `purge` pauses the executor and clears all TODO entries, events, budgets, etc.
- Config is preserved after purge
- Vault provides import/export capabilities for orchestration data
- Debug dump provides detailed internal state for troubleshooting

---

### 2.11 Permissions & Questions

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/permissions` — List pending permission requests
- `POST /api/v1/workspaces/{workspaceID}/permissions/{requestID}/reply` — Reply to permission request
- `GET /api/v1/workspaces/{workspaceID}/questions` — List pending question requests
- `POST /api/v1/workspaces/{workspaceID}/questions/{requestID}/reply` — Reply to question
- `POST /api/v1/workspaces/{workspaceID}/questions/{requestID}/reject` — Reject question
- `POST /api/v1/workspaces/{workspaceID}/questions/{requestID}/consult` — Consult AI on question

**List Permission Requests:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/permissions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Reply to Permission Request:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/permissions/{requestID}/reply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "approved": true,
    "reason": "Approved for development use"
  }'
```

**List Question Requests:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/questions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Reply to Question:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/questions/{requestID}/reply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "answer": "Use the latest LTS version"
  }'
```

**Reject Question:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/questions/{requestID}/reject" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "reason": "Not applicable"
  }'
```

**Consult AI on Question:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/questions/{requestID}/consult" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "model": "gpt-4"
  }'
```

**Notes:**
- Permission requests are from AI assistants needing approval
- Question requests are from AI assistants needing decisions
- `consult` asks a separate AI model for advice (stateless, one-shot)

---

### 2.12 Providers

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/providers` — List providers
- `GET /api/v1/workspaces/{workspaceID}/providers/auth` — Get auth methods
- `POST /api/v1/workspaces/{workspaceID}/providers/{providerID}/oauth/authorize` — Start OAuth
- `POST /api/v1/workspaces/{workspaceID}/providers/{providerID}/oauth/callback` — Complete OAuth

**List Providers:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/providers" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Auth Methods:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/providers/auth" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Start OAuth Authorization:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/providers/{providerID}/oauth/authorize" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Complete OAuth Callback:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/providers/{providerID}/oauth/callback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "code": "oauth-code-from-provider"
  }'
```

**Notes:**
- Providers include OpenAI, Anthropic, Google, etc.
- OAuth flow: authorize → user authorizes → callback completes
- `providers/auth` returns available authentication methods for all providers

---

### 2.13 Skills & Tools

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/skills/{name}` — Get skill
- `PUT /api/v1/workspaces/{workspaceID}/skills/{name}` — Create/update skill
- `PATCH /api/v1/workspaces/{workspaceID}/skills/{name}` — Patch skill
- `DELETE /api/v1/workspaces/{workspaceID}/skills/{name}` — Delete skill
- `GET /api/v1/workspaces/{workspaceID}/skills/marketplace` — Browse marketplace
- `PATCH /api/v1/workspaces/{workspaceID}/skills/builtin/{name}` — Toggle built-in skill
- `GET /api/v1/workspaces/{workspaceID}/tools` — List tools
- `GET /api/v1/exec-skills` — List exec skills

**Get Skill:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/skills/{name}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Create/Update Skill:**

```
curl -s -X PUT "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/skills/{name}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "description": "A custom skill for code review",
    "content": "# Code Review Skill\n\nReview code for best practices...",
    "scope": "workspace"
  }'
```

**Patch Skill:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/skills/{name}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "description": "Updated description"
  }'
```

**Delete Skill:**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/skills/{name}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Browse Marketplace:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/skills/marketplace" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Toggle Built-in Skill:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/skills/builtin/{name}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "enabled": true
  }'
```

**List Tools:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/tools" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Exec Skills:**

```
curl -s "https://api.hoody.icu/api/v1/agent/exec-skills" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Skills are reusable instructions for AI agents
- Scope is only used on create; updating scope requires delete + recreate
- Marketplace is cached for 5 minutes
- `exec-skills` returns scripts available via `exec_user_script`

---

### 2.14 Meta

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/meta/agents` — List agents
- `GET /api/v1/workspaces/{workspaceID}/meta/commands` — List commands
- `POST /api/v1/workspaces/{workspaceID}/meta/dispose` — Dispose workspace
- `GET /api/v1/workspaces/{workspaceID}/meta/events` — Subscribe to events
- `GET /api/v1/workspaces/{workspaceID}/meta/formatter/status` — Get formatter status
- `GET /api/v1/workspaces/{workspaceID}/meta/lsp/status` — Get LSP status
- `GET /api/v1/workspaces/{workspaceID}/meta/path` — Get working directory
- `GET /api/v1/workspaces/{workspaceID}/meta/skills` — List skills
- `GET /api/v1/workspaces/{workspaceID}/meta/vcs` — Get VCS info

**List Agents:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/agents" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Commands:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/commands" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Dispose Workspace:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/dispose" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Subscribe to Events:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/events" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Formatter Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/formatter/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get LSP Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/lsp/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Working Directory:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/path" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Skills:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/skills" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get VCS Info:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/meta/vcs" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Meta endpoints provide workspace metadata and status
- `dispose` cleans up and releases all resources
- `events` provides server-sent events for the workspace
- VCS info includes git branch and other version control details

---

### 2.15 Experimental

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/experimental/tool/ids` — List tool IDs
- `GET /api/v1/workspaces/{workspaceID}/experimental/tool` — List tools with schemas
- `GET /api/v1/workspaces/{workspaceID}/experimental/resource` — List MCP resources

**List Tool IDs:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/experimental/tool/ids" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List Tools with Schemas:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/experimental/tool?providerID=openai&modelID=gpt-4" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**List MCP Resources:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/experimental/resource" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- Experimental endpoints may change without notice
- `tool/ids` returns both built-in and dynamically registered tools
- `tool` returns tools with JSON schema parameters for a specific provider/model
- `resource` returns MCP resources from connected servers

---

### 2.16 Prompt

**Endpoints:**
- `GET /api/v1/agent/prompt` — Submit prompt via query string
- `POST /api/v1/agent/prompt` — Submit prompt (SSE or JSON)
- `POST /api/v1/agent/prompt/sync` — Submit prompt and wait for response

**Submit Prompt (GET):**

```
curl -s "https://api.hoody.icu/api/v1/agent/agent/prompt?q=Hello+world" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Submit Prompt (POST):**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/agent/prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "prompt": "Hello, can you help me?",
    "wait": false
  }'
```

**Submit Prompt (Sync):**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/agent/prompt/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "prompt": "Explain quantum computing"
  }'
```

**Notes:**
- GET endpoint is blocked for cross-site requests
- POST returns SSE stream by default, or JSON if `wait=true`
- Sync endpoint waits for the full response before returning

---

### 2.17 Web Search & Image Gen

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/web-search/status` — Get web search status
- `GET /api/v1/workspaces/{workspaceID}/image-gen/status` — Get image generation status

**Get Web Search Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/web-search/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Get Image Gen Status:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/image-gen/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Notes:**
- These endpoints return configuration and authentication status
- Use to verify web search and image generation capabilities

---

### 2.18 Project

**Endpoints:**
- `GET /api/v1/workspaces/{workspaceID}/project/current` — Get current project
- `PATCH /api/v1/workspaces/{workspaceID}/project/{projectID}` — Update project

**Get Current Project:**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/project/current" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Update Project:**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/project/{projectID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "Updated Project Name",
    "icon": "🚀"
  }'
```

**Notes:**
- `project/current` retrieves the currently active project
- Update project properties such as name, icon, and commands

---

## Advanced Operations

### Full Session Lifecycle

This workflow demonstrates a complete session lifecycle from creation to export.

**Step 1: Create Workspace**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "my-project"
  }'
```

**Step 2: Create Session**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "permission": [
      {
        "permission": "read",
        "pattern": "*",
        "action": "allow"
      }
    ]
  }'
```

**Step 3: Send Message**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "model": {
      "providerID": "openai",
      "modelID": "gpt-4"
    },
    "parts": [
      {
        "type": "text",
        "text": "Analyze this codebase and suggest improvements",
        "time": {
          "start": 1704067200000
        },
        "mime": "text/plain",
        "url": "file:///src/main.ts",
        "source": {
          "text": {
            "value": "function main() { ... }",
            "start": 0,
            "end": 100
          },
          "type": "file",
          "path": "/src/main.ts",
          "range": {
            "start": {
              "line": 1,
              "character": 0
            },
            "end": {
              "line": 10,
              "character": 0
            }
          },
          "name": "main.ts",
          "kind": 1,
          "clientName": "hoody-agent",
          "uri": "file:///src/main.ts",
          "value": "function main() { ... }",
          "start": 0,
          "end": 100
        },
        "name": "analysis-request",
        "prompt": "Analyze and suggest improvements",
        "description": "Codebase analysis request",
        "agent": "default",
        "model": {
          "providerID": "openai",
          "modelID": "gpt-4"
        }
      }
    ]
  }'
```

**Step 4: Get Messages**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/messages" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 5: Fork Session**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/fork" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "messageID": "msg-123"
  }'
```

**Step 6: Get Summary**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/summary" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 7: Export Session**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "format": "markdown"
  }'
```

**Step 8: Delete Session**

```
curl -s -X DELETE "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

---

### Orchestration Workflow

This workflow demonstrates a complete orchestration lifecycle.

**Step 1: Create Phase**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "Phase 1: Setup"
  }'
```

**Step 2: Create Todo Entry**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/todo/entries" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "title": "Setup database",
    "priority": 1
  }'
```

**Step 3: Add Entry to Phase**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/entries" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "entries": ["entry-1"]
  }'
```

**Step 4: Start Executor**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/start" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 5: Monitor Status**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/status" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 6: Answer Questions**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/questions" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/questions/{questionID}/answer" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "answer": "Use PostgreSQL"
  }'
```

**Step 7: Verify Phase**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/phases/{phaseID}/verify" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

---

### MITM Rule Management

This workflow demonstrates MITM rule creation, testing, and monitoring.

**Step 1: Create Rule**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "block-dangerous-commands",
    "toolName": "shell",
    "contentMatch": "rm -rf",
    "action": "block"
  }'
```

**Step 2: Test with Dry Run**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/diagnostics/dry-run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "toolName": "shell",
    "content": "rm -rf /tmp/test"
  }'
```

**Step 3: Get Match Trace**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/diagnostics/match-trace" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "toolName": "shell",
    "content": "rm -rf /tmp/test"
  }'
```

**Step 4: Enable Rule**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/rules/{id}/enable" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 5: Monitor Logs**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/logs" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 6: Subscribe to Events**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/events" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

---

### Memory Management Workflow

This workflow demonstrates memory block and journal management.

**Step 1: Create Memory Block**

```
curl -s -X PUT "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks/project-context" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "content": "This project uses TypeScript with React frontend"
  }'
```

**Step 2: Create Journal Entry**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "content": "Decided to use PostgreSQL for the database",
    "tags": ["decision", "database"]
  }'
```

**Step 3: Search Journal**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/journal/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "query": "database",
    "tags": ["decision"]
  }'
```

**Step 4: Update Memory Block**

```
curl -s -X PATCH "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/blocks/project-context" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "old": "React frontend",
    "new": "Next.js frontend"
  }'
```

**Step 5: View History**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/memory/history" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

---

### MCP Server Lifecycle

This workflow demonstrates MCP server management.

**Step 1: Add MCP Server**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "name": "github-mcp",
    "url": "https://mcp.example.com"
  }'
```

**Step 2: Start OAuth**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/github-mcp/auth" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 3: Complete OAuth Callback**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/github-mcp/auth/callback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -d '{
    "code": "auth-code-from-github"
  }'
```

**Step 4: Connect**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/github-mcp/connect" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 5: List MCP Servers**

```
curl -s "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Step 6: Disconnect**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mcp/github-mcp/disconnect" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

---

### Error Recovery Patterns

**Retry Failed Job:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/jobs/{jobId}/retry" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Rebase Overlay After Drift:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/overlay/rebase" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Reverify Entry After Manual Fix:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/executor/entries/{entryID}/reverify" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Reset Overlay to Base Config:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/mitm/overlay/reset" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

**Purge Orchestration Data:**

```
curl -s -X POST "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/orchestration/purge" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```

---

## Quick Reference

### Endpoint Groups

| Group | Base Path | Count |
|-------|-----------|-------|
| Health | `/api/v1/workspaces/health` | 1 |
| Workspaces | `/api/v1/workspaces` | 7 |
| Sessions | `/api/v1/workspaces/{workspaceID}/sessions` | 49 |
| Branches | `/api/v1/workspaces/{workspaceID}/branches` | 17 |
| Config | `/api/v1/workspaces/{workspaceID}/config` | 8 |
| Files | `/api/v1/workspaces/{workspaceID}/files` | 6 |
| Memory | `/api/v1/workspaces/{workspaceID}/memory` | 14 |
| MCP | `/api/v1/workspaces/{workspaceID}/mcp` | 8 |
| MITM | `/api/v1/workspaces/{workspaceID}/mitm` | 23 |
| Orchestration | `/api/v1/workspaces/{workspaceID}/orchestration` | 61 |
| Permissions | `/api/v1/workspaces/{workspaceID}/permissions` | 2 |
| Providers | `/api/v1/workspaces/{workspaceID}/providers` | 4 |
| Questions | `/api/v1/workspaces/{workspaceID}/questions` | 4 |
| Skills | `/api/v1/workspaces/{workspaceID}/skills` | 6 |
| Tools | `/api/v1/workspaces/{workspaceID}/tools` | 1 |
| Meta | `/api/v1/workspaces/{workspaceID}/meta` | 9 |
| Experimental | `/api/v1/workspaces/{workspaceID}/experimental` | 3 |
| Prompt | `/api/v1/agent/prompt` | 3 |
| Web Search | `/api/v1/workspaces/{workspaceID}/web-search` | 1 |
| Image Gen | `/api/v1/workspaces/{workspaceID}/image-gen` | 1 |
| Project | `/api/v1/workspaces/{workspaceID}/project` | 2 |
| Exec Skills | `/api/v1/exec-skills` | 1 |
| **Total** | | **231** |

### Essential Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `workspaceID` | string | Workspace (project) identifier |
| `sessionID` | string | Session identifier |
| `messageID` | string | Message identifier |
| `phaseID` | string | Orchestration phase identifier |
| `entryID` | string | Todo/budget entry identifier |
| `jobId` / `jobID` | string | Background job identifier |
| `id` | string | Generic resource identifier (branch, rule, tag, etc.) |
| `name` | string | Resource name (skill, MCP server, etc.) |
| `label` | string | Memory block label |
| `providerID` | string | AI provider identifier |
| `modelID` | string | AI model identifier |
| `requestID` | string | Permission/question request identifier |
| `callID` | string | Tool call identifier |
| `projectID` | string | Project identifier |

### Common Query Parameters

| Parameter | Description |
|-----------|-------------|
| `scope` | Filter scope: `global` or `workspace` |
| `status` | Filter by status: `active`, `completed`, `all` |
| `limit` | Pagination limit |
| `cursor` | Pagination cursor |
| `after` | Cursor for incremental message fetching |
| `remote` | Git remote name |
| `path` | File path |
| `pattern` | Search pattern |
| `query` | Search query |

### Response Formats

**List Endpoints:**

```
{
  "items": [],
  "total": 0,
  "cursor": "next-page-cursor"
}
```

**Single Resource:**

```
{
  "id": "resource-id",
  "name": "resource-name",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

**Error Response:**

```
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}
```

### Authentication

All endpoints (except health check) require Bearer token authentication:

```
Authorization: Bearer $HOODY_TOKEN
```

### Base URL

```
https://api.hoody.icu/api/v1/agent
```

### SSE Streams

Several endpoints return Server-Sent Events (SSE) streams:
- Session messages
- MITM events
- Orchestration events/logs
- CLI agent, RSI, and self-tuning job progress

To consume SSE streams:

```
curl -s -N "https://api.hoody.icu/api/v1/agent/workspaces/{workspaceID}/sessions/{sessionID}/messages/{messageID}/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN"
```