dokkaiv0.1.0
RepositoryQuickstart
API Reference

Launch a routine run

Launch a code review or bug-hunt run as a background job on the shared job system.

POST/routines/runsadmin, user

Launch a kind: review or kind: bughunt run and return immediately with run_id/job_id. Poll GET /routines/runs/{run_id} or stream GET /instances/jobs/{job_id}/events for progress.

Pre-flights run before the job is created, in order: the project must have an ingested graph (404); for review, the repo must be git and the refs must resolve (400); named playbooks must exist and apply, at most 4 (400); the resolved LLM must be configured and healthy (400); and bug hunt requires an Ollama-resolved provider (400).

Model resolution — no hardcoded default. model/provider in the body override the active LLM config for this run only; if neither supplies a usable provider+model, the launch fails with 400.

Body

kindenumrequired
review | bughunt.
projectstringrequired
An already-ingested project's project_name.
target_refstring
Required for kind: review (422 if omitted). Branch/ref to review.
base_refstring
review only. Defaults to the repo's default base branch.
scopestring
Required for kind: bughunt (422 if omitted). Free-text description of what to investigate.
path_prefixstring
bughunt only. Restricts reported findings to files under this repo-relative prefix.
modelstring
Override the active LLM config's model for this run only.
providerstring
Override the provider (ollama | openai | anthropic). bughunt requires ollama.
playbooksstring[]
Playbook names pushed into the prompt, priority order, at most 4.

Request

cURL — review
bash
curl -X POST localhost:8000/routines/runs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind":"review","project":"your-repo","target_ref":"feature/my-branch"}'
cURL — bug hunt
bash
curl -X POST localhost:8000/routines/runs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind":"bughunt","project":"your-repo","scope":"unhandled errors in the ingestion pipeline","path_prefix":"src/services"}'

Responses

202Run created and job accepted
json
{
  "run_id": "b0dc2159-...",
  "job_id": "9f094496-..."
}
400Git failure / bad playbook / no LLM / non-Ollama bughunt
json
{ "detail": "No LLM provider configured for this review. POST to /config/llm to set one up, or pass model/provider in the launch payload." }
404Project has no ingested graph
json
{ "detail": "no graph found for project 'your-repo' — run POST /instances/pipeline to ingest it" }
409A job is already running for this project
json
{ "detail": "another job is running for project 'your-repo'" }
← PreviousCheck provider connectivityNext →List routine runs