---
stage: api
requires: components
outputs: "{wiki_dir}/api.md"
version: 2.1.0
estimated_tokens: 2000

guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
  forbidden_actions:
    - "Delete any files"
    - "Modify any source files"
  read_only: true
---
# Stage 8: API Documentation

Generate comprehensive API endpoint documentation with routes, methods, parameters, request/response schemas, and examples.

## Prerequisites

- Stage 07 completed with components documented
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Discovery cache loaded: LIMITS

## Critical Rules

| Rule | Action |
|------|--------|
| Components required | **MUST** verify {wiki_dir}/components/README.md exists |
| Search before skip | **MUST** search for endpoints before deciding to skip |
| Trace endpoints | **SHOULD** document request/response schemas when available |
| Skip if none | **MAY** skip if no API endpoints found (library projects) |

---

{{include:ai-cache-enforcement.md}}

{{include:understand-fast-path.md}}

---

## Step 1: Verify Previous Stage

```bash
civyk-hatch deepwiki-update-state verify-stage --stage=08-api --wiki-dir={wiki_dir}
```

---

## Step 2: Load Discovery Cache

```bash
civyk-hatch deepwiki-update-state show --wiki-dir={wiki_dir}
# Extract: LIMITS = discovery_cache.project_size.limits
# Use LIMITS.endpoints for architecture(action="endpoints", limit=LIMITS.endpoints)
```

**MCP/CLI conversion (if REPOIX_MODE == "cli"):**

| MCP Call | CLI Equivalent |
|----------|----------------|
| `architecture(action="endpoints", limit=100)` | `civyk-repoix query architecture --action endpoints --limit 100` |
| `search(action="code", query="@route", is_regex=true)` | `civyk-repoix query search --action code --query "@route" --is-regex true` |
| `context(action="task", task="...", token_budget=2000)` | `civyk-repoix query context --action task --task "..." --token-budget 2000` |

---

## Step 3: Find API Endpoints

```text
# Get all endpoints
architecture(action="endpoints", limit=200)
context(action="task", task="document all API endpoints and routes", token_budget=2000)
architecture(action="components")

# Framework-specific routes
# Python (Flask/FastAPI)
search(action="code", query="@app.route|@app.get|@app.post|@router.get|@router.post", is_regex=true, limit=100)

# JavaScript (Express/NestJS)
search(action="code", query="express.Router|app.get|@Get|@Post|@Controller", is_regex=true, limit=100)

# Java (Spring)
search(action="code", query="@RequestMapping|@GetMapping|@PostMapping", is_regex=true, limit=100)

# Go (Gin/Echo/Fiber)
search(action="code", query="r.GET|r.POST|e.GET|e.POST", is_regex=true, limit=100)

# C#/.NET
search(action="code", query="\\[HttpGet\\]|\\[HttpPost\\]|\\[ApiController\\]", is_regex=true, limit=100)

# Ruby on Rails
search(action="code", query="resources :|get |post |put |delete ", is_regex=true, file_pattern="*routes*", limit=50)

# PHP Laravel
search(action="code", query="Route::get|Route::post|Route::resource", is_regex=true, limit=50)

# Rust (Actix, Axum, Rocket)
search(action="code", query="#\\[get|#\\[post|web::get|axum::Router", is_regex=true, limit=50)

# GraphQL
search(action="code", query="@Query|@Mutation|@Resolver|type Query", is_regex=true, limit=50)

# gRPC
files(pattern="**/*.proto", limit=50)

# WebSocket
search(action="code", query="@WebSocket|socket.on|@SubscribeMessage", is_regex=true, limit=50)
```

---

## Step 4: Trace Each Endpoint

For each endpoint:

```text
# Find controller
search(action="symbols", query="<ControllerName>", kind="class")
file(action="symbols", path="<controller_file>", kinds=["method"])
file(action="imports", path="<controller_file>")

# Read implementation
# Read file: <controller_file>
# -> Extract route, parameters, validation, response format

# Get DTOs/schemas
search(action="symbols", query="%<EndpointName>%Dto", kind="class", limit=20)
search(action="symbols", query="%<EndpointName>%Schema", kind="class", limit=20)
# Read file: <dto_file>

# Get examples from tests
file(action="related", path="<controller_file>", relationship_types=["test"])
# Read file: <test_file>

# Understand usage
symbol(action="callers", fqn="<method_fqn>", depth=2)

# Find duplicate endpoint patterns (consolidation candidates)
quality(action="duplicates", source_only=true, similarity_threshold=0.7, limit=30)
```

---

## Step 5: Generate Documentation

Write `{wiki_dir}/api.md` using this template:

{{include:wiki/api-template.md}}

**Fill placeholders with:** API overview, authentication mechanism, endpoints table, per-endpoint details (parameters, schemas, responses), error codes, rate limiting, versioning strategy.

---

## Step 6: Complete Stage

```bash
civyk-hatch deepwiki-update-state stage --stage=08-api --status=completed --artifacts="{wiki_dir}/api.md" --wiki-dir={wiki_dir}
```

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 08-api

  Generated: {wiki_dir}/api.md
  Endpoints: {count}
  Methods covered: GET, POST, PUT, DELETE

  Next: Run {next_command}
===========================================================
```

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| No API endpoints | Skip stage (library project) |
| GraphQL instead of REST | Document schema and resolvers |
| gRPC/Protobuf | Document RPC methods and messages |
| WebSocket endpoints | Document event types and message formats |

---

## Next Stage

Run `{next_command}` - CLI auto-detects current stage and emits next prompt.
