Sessions
Create, prompt, fork, cancel, trim, and stream agent sessions.
Overview
Section titled “Overview”The Hoody Agent is a fully HTTP-driven AI coding agent that runs inside a containerised Kit service. It exposes every capability of an interactive coding session — session lifecycle, prompt streaming, todo triage, skills, memory, tools, workflows, and project-level integrations such as GitHub — as REST endpoints under /api/v1/agent/.... Because the entire surface is HTTP, the same agent can be driven from cURL, a backend service, a CI pipeline, or the Hoody SDK without any local binary or terminal session.
Unlike the management Hoody API, the Agent is scoped to a single container instance. All requests are routed through the Hoody proxy to a container URL of the form https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu, and every endpoint is namespaced beneath /api/v1/agent/. Treat that container URL as the authoritative base URL for every sub-page in this section; do not use https://api.hoody.icu or localhost for agent calls.
Capabilities
Section titled “Capabilities”The Agent surface is organised into focused sub-APIs. Each link below opens the dedicated reference page for that group of endpoints.
Todos
File, claim, run, snooze, and triage the agent todo queue.
Models & Providers
List models and manage LLM providers, including API keys and OAuth pools.
Skills
Skill hub, CRUD, install, import, and toggles.
Chat Agents
Create and customise chat-agent definitions, tools, and models.
Memory
Persistent memory items, the project graph, and hybrid recall search.
GitHub
Auth, clone, commit, sync, branches, repos, and pull requests.
Hooks
Lifecycle hooks: upsert, toggle, test, reload, and trust.
MCP Servers
Configure MCP servers: list with live state, add, enable, remove, import, probe, and reconnect.
Tools
Tool catalogue, schemas, and sessionless or in-session tool runs.
Workflows
Define, run, and manage multi-step agent workflows.
Settings
Agent settings, fusion composites, and BYOA / ACP backends.
Logs
Query, stream, and inspect agent logs.
Loops
Scheduled self-prompting loops on a session.
Tasks
Inspect and cancel a session’s background tasks.
Jobs
Poll and cancel async jobs and read their results.
Statistics
Cross-session statistics and usage rollups.
Discovery
List realms and containers for session binding.
Headless
Fire one-shot headless agent runs.
System
Health, metrics, and the live OpenAPI spec.
Base URL
Section titled “Base URL”Every Agent endpoint is reached through the Hoody proxy against the container URL:
https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icuAppend the API path under /api/v1/agent/.... For example, to list sessions:
https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessionsWhen to use the Agent API
Section titled “When to use the Agent API”Use the Agent API when you need to:
- Drive a coding session from a backend — start a session, stream completions, observe todo progress, and cancel mid-run, all from a server you control.
- Automate agent workflows — combine sessions, todos, tools, and workflows to express multi-step pipelines (for example, nightly refactors or PR review bots).
- Integrate agent capabilities into a product — wrap skills, memory, or GitHub operations in your own UI without running the Hoody desktop binary.
- Inspect and operate an existing container — query logs, statistics, jobs, and tasks to debug or audit a live agent.
For account-level concerns such as creating containers, provisioning projects, or managing organisations, use the management Hoody API at https://api.hoody.icu instead — those endpoints are documented under the /api/ root of this reference.