> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Generator

> Auto-generate comprehensive API documentation

The `praisonai docs api-md` command generates a comprehensive API reference document (`api.md`) at the repository root, covering all public exports from praisonaiagents, praisonai, CLI commands, and TypeScript packages.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Generate/update api.md
praisonai docs api-md

# Check if api.md is up to date (for CI)
praisonai docs api-md --check

# Print to stdout
praisonai docs api-md --stdout
```

## Commands

### Generate API Reference

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai docs api-md
```

Generates `api.md` at the repository root with all public API surfaces.

**Expected Output:**

```
✓ Generated /path/to/repo/api.md
```

### Check Mode

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai docs api-md --check
```

Verifies that `api.md` is up to date. Exits with code 1 if outdated.

**Use Case:** CI/CD pipelines to ensure API docs are current.

**Expected Output (when current):**

```
✓ /path/to/repo/api.md is up to date
```

**Expected Output (when outdated):**

```
✗ api.md is out of date. Run: praisonai docs api-md --write
```

### Print to Stdout

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai docs api-md --stdout
```

Prints the generated API reference to stdout instead of writing to file.

**Use Case:** Preview changes or pipe to other tools.

## Generated Content

The `api.md` file includes:

### Python Core SDK (praisonaiagents)

* **Agents** - Agent, Agents, AutoAgents, DeepResearchAgent, etc.
* **Tools** - BaseTool, FunctionTool, MCP, Tools
* **Workflows** - Workflow, Task, Pipeline
* **Memory** - Memory, Session, Context
* **Knowledge** - Knowledge, RAG, Chunking
* **Other** - Handoff, Guardrails, Skills, Telemetry

### Python Wrapper (praisonai)

* PraisonAI, Deploy, Recipe
* Re-exported praisonaiagents symbols

### CLI Commands

All `praisonai` CLI commands with their subcommands and flags.

### TypeScript SDK (praisonai-ts)

All exported classes, types, and functions from the TypeScript package.

## Output Format

The generated `api.md` follows OpenAI SDK-style formatting:

````markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# PraisonAI API Reference

## Agents

Types:
```python
from praisonaiagents import Agent, AgentTeam
````

Methods:

* <code title="class Agent">Agent.<a href="./src/...">start</a>(prompt: str)</code>
* <code title="class Agent">Agent.<a href="./src/...">chat</a>(message: str)</code>

````

## Discovery Algorithm

The generator uses AST-based static analysis to discover symbols:

1. **Parse `__all__`** - Respects explicit public API declarations
2. **Lazy-loaded symbols** - Extracts symbols from `__getattr__` functions
3. **Direct imports** - Tracks `from X import Y` statements
4. **Method extraction** - Discovers class methods via AST
5. **CLI commands** - Parses Typer command definitions
6. **TypeScript exports** - Regex-based export parsing

## Performance

- **Import time:** ~30ms (stdlib only: ast, re, sys, pathlib)
- **No heavy dependencies** - No doc generation libraries
- **Lazy loading** - Generator only loaded when explicitly called
- **Zero runtime impact** - Not loaded during normal package usage

## CI/CD Integration

Add to your CI pipeline to ensure API docs stay current:

```yaml
# .github/workflows/ci.yml
- name: Check API docs
  run: praisonai docs api-md --check
````

## Contributing

When adding new public APIs:

1. Add the symbol to `__all__` in the relevant `__init__.py`
2. Run `praisonai docs api-md` to regenerate
3. Commit both code changes and updated `api.md`

## Python API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai._dev.api_md import generate_api_md
from pathlib import Path

# Generate api.md
exit_code = generate_api_md(
    repo_root=Path.cwd(),
    output_path=Path("api.md"),
    check=False,
    stdout=False
)

# Check mode
exit_code = generate_api_md(
    repo_root=Path.cwd(),
    output_path=Path("api.md"),
    check=True
)
# Returns 0 if current, 1 if outdated
```

## Related

* [CLI Reference](/cli/cli-reference) - Complete CLI command tree
* [Docs Management](/cli/docs) - Project documentation
* [Examples](/cli/examples) - Code examples validation