Sessions
Create, prompt, fork, cancel, trim, and stream agent sessions.
The Hoody Agent is a fully HTTP-driven AI coding agent that runs inside a Hoody container. Every aspect of an agent session — creation, prompting, tool use, memory, hooks, workflows, GitHub integration, and background tasks — is exposed as a REST endpoint under /api/v1/agent/.... This makes it possible to drive headless coding sessions from any HTTP client, CI pipeline, or automation script without a local editor or interactive UI.
The Agent service is intentionally comprehensive: it covers the lifecycle of a session from discovery and creation through streaming, forking, and cancellation; it exposes a todo queue, a skill hub, a tool catalogue, and a workflow engine; it persists memory across runs and integrates with GitHub for source control; and it surfaces operational endpoints for hooks, MCP servers, logs, jobs, and statistics. Each of those areas is documented on its own sub-page.
Base URL
Section titled “Base URL”The Hoody Agent is an in-container Kit service reached through the Hoody proxy. All endpoints share the same container-scoped base URL:
https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.comEvery operation lives under /api/v1/agent/... (for example https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions). This is distinct from the management Hoody API at https://api.hoody.com — agent endpoints are never served from the management host.
Endpoint groups
Section titled “Endpoint groups”The Agent API is organised into the following groups. Each card links to the dedicated reference page for that group.
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 toggle skills available to the agent.
Chat Agents
Create and customise chat-agent definitions, tools, and model bindings.
Memory
Persistent memory items, the project graph, and hybrid recall search.
GitHub
Auth, clone, commit, sync, branches, repos, and pull request operations.
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.
Authentication
Section titled “Authentication”Agent endpoints are reached through the Hoody proxy and inherit the proxy’s authentication model. Requests must carry a valid Hoody bearer token in the Authorization header, formatted as Bearer <token>. The token grants access to the specific container identified in the base URL; cross-container access is not permitted.
Choosing a starting point
Section titled “Choosing a starting point”If you are new to the Hoody Agent API, the typical flow is:
- Call the Discovery endpoints to confirm the container and realm you want to bind a session to.
- Use the Sessions endpoints to create a session and stream its events.
- Drive the agent with the Chat Agents, Tools, Skills, Memory, Hooks, and MCP Servers endpoints as needed.
- Inspect operational state through Tasks, Jobs, Logs, and Statistics endpoints.
For one-off automation that does not need a long-lived session, the Headless group exposes a single-call entry point that creates a session, runs it to completion, and returns the result.