# API Reference

## Endpoints

- `GET /`: server metadata.
- `GET /health`: health probe.
- `GET /metrics`: Prometheus metrics (when enabled).
- `POST /automation/webhook`: ingest policy-controlled webhook events.
- `POST /automation/jobs/run`: run policy-controlled automation jobs.
- `GET /mcp/tools`: list tool definitions.
- `POST /mcp/tool/call`: execute a tool (`Authorization: Bearer <api-key>` required except in explicitly disabled auth mode).
- `GET /mcp/sse` and `POST /mcp/sse`: MCP SSE transport.

## Automation Jobs

`POST /automation/jobs/run` supports:
- `dependency_hygiene_scan` (read-only scaffold).
- `stale_issue_detection` (read-only issue age analysis).
- `auto_issue_creation` (write-mode + whitelist + policy required).

## Read Tools

- `list_repositories`.
- `get_repository_info` (`owner`, `repo`).
- `get_file_tree` (`owner`, `repo`, optional `ref`, `recursive`).
- `get_file_contents` (`owner`, `repo`, `filepath`, optional `ref`).
- `search_code` (`owner`, `repo`, `query`, optional `ref`, `page`, `limit`).
- `list_commits` (`owner`, `repo`, optional `ref`, `page`, `limit`).
- `get_commit_diff` (`owner`, `repo`, `sha`).
- `compare_refs` (`owner`, `repo`, `base`, `head`).
- `list_issues` (`owner`, `repo`, optional `state`, `page`, `limit`, `labels`).
- `get_issue` (`owner`, `repo`, `issue_number`).
- `list_pull_requests` (`owner`, `repo`, optional `state`, `page`, `limit`).
- `get_pull_request` (`owner`, `repo`, `pull_number`).
- `list_labels` (`owner`, `repo`, optional `page`, `limit`).
- `list_tags` (`owner`, `repo`, optional `page`, `limit`).
- `list_releases` (`owner`, `repo`, optional `page`, `limit`).

## Write Tools (Write Mode Required)

- `create_issue` (`owner`, `repo`, `title`, optional `body`, `labels`, `assignees`).
- `update_issue` (`owner`, `repo`, `issue_number`, one or more of `title`, `body`, `state`).
- `create_issue_comment` (`owner`, `repo`, `issue_number`, `body`).
- `create_pr_comment` (`owner`, `repo`, `pull_number`, `body`).
- `add_labels` (`owner`, `repo`, `issue_number`, `labels`).
- `assign_issue` (`owner`, `repo`, `issue_number`, `assignees`).

## Validation and Limits

- All tool argument schemas reject unknown fields.
- List responses are capped by `MAX_TOOL_RESPONSE_ITEMS`.
- Text payloads are capped by `MAX_TOOL_RESPONSE_CHARS`.
- File reads are capped by `MAX_FILE_SIZE_BYTES`.

## Error Model

- Policy denial: HTTP `403`.
- Validation error: HTTP `400`.
- Auth error: HTTP `401`.
- Rate limit: HTTP `429`.
- Internal errors: HTTP `500` without stack traces in production.