# AI Code Generation

**Page:** api/exec/ai-generation

[Download Raw Markdown](./api/exec/ai-generation.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## AI Code Generation

The AI Code Generation API provides programmatic access to Hoody's directive parsing and code generation engine. It enables you to transform natural language directives, structured prompts, or annotated instructions into executable code across multiple languages and frameworks.

This endpoint group is designed for building autonomous coding agents, IDE plugins, CI/CD automations, and developer tools that need to delegate code synthesis to a managed AI backend without managing model infrastructure directly.

### When to use these endpoints

Use the AI Code Generation API when you need to:

- **Parse structured directives** — Convert annotated instruction sets (similar to `.claude` or `.github` workflow files) into actionable code generation tasks.
- **Generate code from intent** — Produce source files, patches, or full project scaffolds from high-level descriptions.
- **Stream generation output** — Receive incremental token streams for real-time editor integration.
- **Refactor or extend existing code** — Provide context (files, snippets, repositories) and receive targeted modifications.

### How it works

A typical request flows through three stages:

1. **Directive submission** — The client posts a directive describing the desired output, optionally including language, framework, target files, and contextual code.
2. **Context assembly** — Hoody resolves referenced files, dependencies, and project metadata to build a generation context.
3. **Generation & delivery** — The engine produces code, returning either a complete response or a token stream depending on the requested mode.


  All generation requests are asynchronous when streaming is enabled. Clients should be prepared to handle incremental responses, server-sent events, or webhook callbacks depending on the integration mode.


### Authentication

All requests must include a valid Hoody API token in the `Authorization` header using the `Bearer` scheme:

`Authorization: Bearer <HOODY_API_KEY>`

Generate or rotate tokens from the **Dashboard → API Keys** section. Tokens are scoped to the issuing workspace and inherit its permissions.

### Rate limits and quotas

AI Code Generation requests count against your workspace's generation quota. Quotas are enforced per minute (burst) and per day (sustained). When a limit is exceeded, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating when the next request can be made.


  Quota consumption is non-recoverable. A request that fails mid-generation still counts against your daily limit. Design retry logic to back off on `429` and `5xx` responses.


### Next steps

- Review the **Quickstart** guide for a working example in your language of choice.
- Consult the **Directive Reference** for the full schema of accepted inputs.
- See **Streaming Responses** for SSE integration details.