The OpenAPI document describes boards: list, read, write, delete, panels, pins, sources and query #4859

The OpenAPI document now has rows for all nine boards routes, so a harness can list, read, write, delete, query and pin boards from the document alone. test/openapi.test.ts passes (9 tests, including the new one) and bun x tsc --noEmit is clean. I didn't run the whole check.

The rows sit right after GET /api/v1/migrate/{job} in src/contract/openapi.ts, in this order:

• GET /api/v1/boards
• GET and POST /api/v1/boards/pins
• GET /api/v1/boards/sources
• POST /api/v1/boards/query
• GET, PUT and DELETE /api/v1/boards/{slug}
• GET /api/v1/boards/{slug}/panels/{id}

All are auth: true. The handlers only admit a site admin who is a person, and the list and read rows say so.

• "put": I added it to the Route method type here, since #4844 hadn't yet.
• Query row: it lists the body fields runQuery reads (source, from, to, filter, groupBy, step, aggregate, column, series). Its refusals are bad_json, too_large and bad_query, and the bad_query text names the unknown-source case.
• Other refusals: the pins, write and panel rows list theirs, each with its status.
• New test: the boards routes are described asserts each new path and method is in the served document, and that the query row mentions unknown source.

I did not change any handler.

I did not describe the response shapes beyond the summary text, as the existing rows don't either. The PUT board body is also described only by its top-level fields (title, range, refresh, panels). The panel schema isn't spelled out.

Closes #4852

The OpenAPI document now has rows for all nine boards routes, so a harness can list, read, write, delete, query and pin boards from the document alone. test/openapi.test.ts passes (9 tests, including the new one) and bun x tsc --noEmit is clean. I didn't run the whole check.

The rows sit right after GET /api/v1/migrate/{job} in src/contract/openapi.ts, in this order:

• GET /api/v1/boards
• GET and POST /api/v1/boards/pins
• GET /api/v1/boards/sources
• POST /api/v1/boards/query
• GET, PUT and DELETE /api/v1/boards/{slug}
• GET /api/v1/boards/{slug}/panels/{id}

All are auth: true. The handlers only admit a site admin who is a person, and the list and read rows say so.

• "put": I added it to the Route method type here, since #4844 hadn't yet.
• Query row: it lists the body fields runQuery reads (source, from, to, filter, groupBy, step, aggregate, column, series). Its refusals are bad_json, too_large and bad_query, and the bad_query text names the unknown-source case.
• Other refusals: the pins, write and panel rows list theirs, each with its status.
• New test: the boards routes are described asserts each new path and method is in the served document, and that the query row mentions unknown source.

I did not change any handler.

I did not describe the response shapes beyond the summary text, as the existing rows don't either. The PUT board body is also described only by its top-level fields (title, range, refresh, panels). The panel schema isn't spelled out.

I merged main into the branch, resolved the two conflicts, and pushed. bun x tsc --noEmit is clean and test/openapi.test.ts passes (18 tests). I did not run the rest of the suite; the forge runs the full check on the push.

• src/contract/openapi.ts: The boards rows (list, read, write, delete, panels, pins, sources, query) are kept. I dropped the GET /api/v1/migrate/{job} row from this branch because main already describes that route further up, so keeping both would have listed it twice.
• test/openapi.test.ts: I kept both tests, "the boards routes are described" from this branch and the new ones from main.

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

This pull now merges with main again. The nine boards rows are in the OpenAPI document, each in its own file under src/contract/openapi/routes/ as main's #5949 layout requires. The OpenAPI tests and the type check pass. I didn't run the whole suite; the forge's check runs it on this push.

• Merge: src/contract/openapi.ts and test/openapi.test.ts conflicted. I took main's openapi.ts and rebuilt the generated routes/index.ts with bun scripts/openapi-routes.ts. The boards test and main's repository-reads test both stay in test/openapi.test.ts.
• MCP: this pull adds no MCP tool, so the #5932 split didn't touch it.
• Review point 2: the PUT refusals now list exists (409). boardFailed can return it, and I didn't check whether writeBoard ever produces it, so I added it rather than confirm it never does.
• Allowlist: I removed the nine boards entries from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts. That test warns when a described route is still on the list.
• Not done: review point 1, typed response and panel schemas. The Route shape has no way to express them yet, so a PUT body is still top-level fields and panels is still an untyped array. That is a follow-up covering every route.

To try it, open /contract/openapi.json on the preview and look for /api/v1/boards and the eight paths under it.