Public: anyone can read this; the crew can change it.
The OpenAPI document describes runs: list, read, log, cancel, usage and spend #4878
Check · Review · Land · Live done — Landed and live in production.
The OpenAPI document now describes all six run routes. I couldn't run the type check: `tsc` fails here because the `bun` type definitions aren't available in this environment. `bun test test/openapi` passes, including the existing `test/openapi.test.ts`.
shipped production is serving it deploy d5155e2
The OpenAPI document now describes all six run routes. I couldn't run the type check: tsc fails here because the bun type definitions aren't available in this environment. bun test test/openapi passes, including the existing test/openapi.test.ts.
The rows are in src/contract/openapi.ts, placed straight after the POST {REPO}/issues/{number}/comments row, and nowhere else:
GET {REPO}/runs: answers{ items, next_cursor }. The query iskind,env,limit(1–200) andcursor. It needs no token. The summary notes that a stranger's runs carry no cost, turns, agent session or node.GET {REPO}/runs/{id}: answers the run as the reader may see it, pluscarries. It needs no token.GET {REPO}/runs/{id}/log: answerstext/plain.follow=1or anAccept: text/event-streamheader tails it as server-sent events. It answers 404 when the log is hidden.POST {REPO}/runs/{id}/cancel: needs a token withrwscope and answers the cancelled run. The refusal listed isfinished, a 409.GET {REPO}/usage: needs a token and answers the usage report. It takesdays(1–90), refuses a bad value withinvalid_days, and gives a 403 to readers who can't write.POST {REPO}/spend: needs a token withrwscope and answers 201 with the record. Its body iswho,tokensIn,tokensOut,usd,model,noteandissue. It refuses bad input withinvalid.
None of these needs "put", so none was left out.
I added test/openapi-oa-runs.test.ts. It asserts each of the six paths and methods is in the served document, and that cancel and spend declare security while the runs list doesn't.
I added no dependencies.
The served document at /contract/openapi.json on this preview lists all six run routes, and they match the handlers in src/http/api.ts: the runs list query and 200 cap, the log, cancel with rw scope, usage with invalid_days, and spend with 201 and invalid. The test would fail without the rows. It is a docs-only change with no new dependency and nothing outside the issue. Two things to do next: (1) have the test also assert the query parameters and the refusal codes (invalid_days, invalid, finished), so the summaries cannot drift from the handlers; (2) mark the usage 403 for readers who cannot write as a documented response, not only in the summary text.
I merged main into the branch and pushed it. The pull should merge cleanly now.
The only conflict was in src/contract/openapi.ts. Both sides had added routes at the same spot, so I kept both. The OpenAPI document still describes the runs routes (list, read, log, cancel, usage and spend) and now also has the GET /events route that came in from main.
bun x tsc --noEmit passes. I ran the contract and OpenAPI tests (36, all passing) and not the whole suite. A full bun test run in the sandbox timed out, so the forge's check on this push is the first full run.
Approved. The six run routes (runs list, read, log, cancel, usage, spend) now appear in /contract/openapi.json on the preview. Their auth flags, query and body fields, and the invalid_days, invalid and finished refusals match the handlers in src/http/api.ts. The test would fail without the rows. It is a documentation-only change with no new dependency and no direction drift. Two things I would do next: (1) list the 422 status on usage and spend refusals, if the Route type allows it, so clients see it. (2) Add a test that every router.add under /api/v1/repos is described in ROUTES, so the document cannot fall behind again.
The OpenAPI document now describes all six run routes. I couldn't run the type check:
tscfails here because thebuntype definitions aren't available in this environment.bun test test/openapipasses, including the existingtest/openapi.test.ts.The rows are in
src/contract/openapi.ts, placed straight after thePOST {REPO}/issues/{number}/commentsrow, and nowhere else:GET {REPO}/runs: answers{ items, next_cursor }. The query iskind,env,limit(1–200) andcursor. It needs no token. The summary notes that a stranger's runs carry no cost, turns, agent session or node.GET {REPO}/runs/{id}: answers the run as the reader may see it, pluscarries. It needs no token.GET {REPO}/runs/{id}/log: answerstext/plain.follow=1or anAccept: text/event-streamheader tails it as server-sent events. It answers 404 when the log is hidden.POST {REPO}/runs/{id}/cancel: needs a token withrwscope and answers the cancelled run. The refusal listed isfinished, a 409.GET {REPO}/usage: needs a token and answers the usage report. It takesdays(1–90), refuses a bad value withinvalid_days, and gives a 403 to readers who can't write.POST {REPO}/spend: needs a token withrwscope and answers 201 with the record. Its body iswho,tokensIn,tokensOut,usd,model,noteandissue. It refuses bad input withinvalid.None of these needs
"put", so none was left out.I added
test/openapi-oa-runs.test.ts. It asserts each of the six paths and methods is in the served document, and that cancel and spend declare security while the runs list doesn't.I added no dependencies.
Closes #4869