API reference¶

Start the server with developer serve (default localhost:6768). No auth required.

Endpoints¶

Health¶

GET /

curl localhost:6768/

Returns {"status": "ok"}.

Repos¶

GET /repos

curl localhost:6768/repos

Returns the list of configured repos from developer.yaml.

[
  {"name": "myrepo", "owner": "gregology", "repo": "myrepo", "provider": "claude"},
  ...
]

Add repo¶

POST /repos

curl -X POST localhost:6768/repos \
  -H 'Content-Type: application/json' \
  -d '{"owner": "myorg", "repo": "my-new-repo"}'

{
  "owner": "myorg",
  "repo": "my-new-repo",
  "provider": null
}

Clones the repo, runs an investigation agent to discover setup commands, testing philosophy, and quality tools, then writes the config to developer.yaml. Returns 202 with a task ID. Returns 409 if the repo already exists in config.

Pipelines¶

All pipeline endpoints accept a JSON body and return immediately with a task ID. The pipeline runs in the background. Poll /tasks/{task_id} for progress.

{"task_id": "a1b2c3d4e5f6", "status": "pending"}

The repo field in all requests accepts a config key name (e.g. "myrepo") or "owner/repo" format.

Resolve¶

POST /resolve

curl -X POST localhost:6768/resolve \
  -H 'Content-Type: application/json' \
  -d '{"repo": "myrepo", "issue": 25, "dry_run": false}'

{
  "repo": "myrepo",
  "issue": 25,
  "dry_run": false,
  "provider": null
}

Review¶

POST /review

curl -X POST localhost:6768/review \
  -H 'Content-Type: application/json' \
  -d '{"repo": "myrepo", "pr": 42, "dry_run": false}'

{
  "repo": "myrepo",
  "pr": 42,
  "dry_run": false,
  "provider": null
}

Address¶

POST /address

curl -X POST localhost:6768/address \
  -H 'Content-Type: application/json' \
  -d '{"repo": "myrepo", "pr": 42, "dry_run": false}'

{
  "repo": "myrepo",
  "pr": 42,
  "dry_run": false,
  "provider": null
}

Audit¶

POST /audit/{audit_type}

Where audit_type is one of docs, refactor, or tests.

curl -X POST localhost:6768/audit/docs \
  -H 'Content-Type: application/json' \
  -d '{"repo": "myrepo", "dry_run": false, "limit": 3}'

{
  "repo": "myrepo",
  "dry_run": false,
  "limit": 3,
  "provider": null
}

Validate¶

POST /validate

curl -X POST localhost:6768/validate \
  -H 'Content-Type: application/json' \
  -d '{"repo": "myrepo", "dry_run": false}'

{
  "repo": "myrepo",
  "validate_all": false
}

Provide either repo or set validate_all to true.

Tasks¶

List all tasks¶

GET /tasks

curl localhost:6768/tasks

Returns all tasks, newest first.

Get task detail¶

GET /tasks/{task_id}

curl localhost:6768/tasks/a1b2c3d4e5f6

Returns status, log messages, result, and error (if any).

{
  "task_id": "a1b2c3d4e5f6",
  "status": "completed",
  "log": [
    "Fetching issue #25 from gregology/myrepo",
    "Setting up repository",
    "Running resolve pipeline",
    "Resolve pipeline complete"
  ],
  "result": {"pipeline": "resolve", "issue": 25, "dry_run": false},
  "error": null
}

Status values: pending, running, completed, failed.

Response schemas¶

The result field in a completed task varies by pipeline. All results include "pipeline" and "dry_run" fields.

Resolve¶

{
  "pipeline": "resolve",
  "issue": 25,
  "dry_run": false,
  "decision": "propose",
  "pr_url": "https://github.com/owner/repo/pull/26"
}

Field	Type	Description
`issue`	`int`	Issue number that was resolved
`decision`	`string`	Triage decision: `ask`, `propose`, `action_proposed`, `action_direct`, `decline`, `decision`, or `decompose`
`pr_url`	`string`	URL of the created pull request (present only when a PR was opened)

Review¶

{
  "pipeline": "review",
  "pr": 42,
  "dry_run": false,
  "comment_url": "https://github.com/owner/repo/pull/42#issuecomment-123"
}

Field	Type	Description
`pr`	`int`	Pull request number that was reviewed
`comment_url`	`string`	URL of the posted review comment (present only when a comment was posted)

Address¶

{
  "pipeline": "address",
  "pr": 42,
  "dry_run": false,
  "comment_url": "https://github.com/owner/repo/pull/42#issuecomment-456"
}

Field	Type	Description
`pr`	`int`	Pull request number
`comment_url`	`string`	URL of the response comment (present only when a comment was posted)

Audit¶

{
  "pipeline": "audit",
  "audit_type": "docs",
  "dry_run": false,
  "findings_count": 2,
  "findings": [
    {"title": "Add missing docstrings", "labels": ["documentation"]},
    {"title": "Update outdated README section", "labels": ["documentation"]}
  ]
}

Field	Type	Description
`audit_type`	`string`	One of `docs`, `refactor`, or `tests`
`findings_count`	`int`	Number of findings
`findings`	`array`	List of findings, each with `title` (`string`) and `labels` (`string[]`)

Add repo¶

{
  "pipeline": "add_repo",
  "repo": "my-new-repo",
  "config_saved": true
}

Field	Type	Description
`repo`	`string`	Repo name (the `repo` portion of `owner/repo`)
`config_saved`	`bool`	`true` if config was written to `developer.yaml` (`false` if the agent produced no output)

Validate¶

{
  "pipeline": "validate",
  "results": {"myrepo": true, "other-repo": false},
  "all_passed": false
}

Field	Type	Description
`results`	`object`	Map of repo name to pass/fail (`bool`)
`all_passed`	`bool`	`true` if every repo passed validation

Error responses¶

400 -- invalid request (bad audit type, missing required fields)
404 -- unknown repo or task ID
409 -- repo already exists in config (add repo)

Errors return {"detail": "..."}.

Interactive API docs¶

When the server is running, FastAPI serves auto-generated interactive documentation:

Swagger UI -- http://localhost:6768/docs
ReDoc -- http://localhost:6768/redoc

These are built from the Pydantic models and always reflect the current API surface.