62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# 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.
|