docs: update API reference for stop session endpoint

[tembo]

What changed

Documents the POST /session/{sessionId}/stop endpoint in the API reference:

• Added the path/operation to openapi.documented.yml (hosted API) and openapi.self-hosted.yml (self-hosted API), matching the existing style/schema conventions used by neighboring /session/* endpoints.
• Added POST /session/{sessionId}/stop to the "Sessions" navigation group in docs.json for both the "Tembo API" and "Self-Hosted API" tabs.

No other content was touched.

Why

In monorepo release v0.2.820, the session-stop route was refactored out of the internal session router into a shared stopSessionRouter and mounted directly on the public API session router for the first time:

• apps/api/src/server/routes/session/stop.ts (new file) — defines POST /:id/stop, tagged ['session', 'public-api'], returning { cancelledSessions, cancelledJobs, stoppedRuntimeSessions, interruptedRuntimeTurns, cancelledRuntimeTurns } (all numbers), with 400/404 error responses.
• apps/api/src/server/routes/public-api/session.ts — now does userSession.route('/', stopSessionRouter), which it did not do before this release.
• apps/api/src/server/routes/public-api/index.ts mounts that router at /public-api/session, and compatibility.ts rewrites public-facing /session/... requests to /public-api/session/..., matching the path convention already used for /session/create, /session/list, /session/search, and /session/{sessionId}/messages in the docs.

Before this release, "stop" only existed on the internal (non-public) session router, so it was correctly absent from the public API reference. Now that it's part of the public API surface, the reference docs and self-hosted equivalent were missing this endpoint and the nav had no entry for it.

Evidence

• Monorepo commit 0d21df997 (tag v0.2.820), diffed against the previously-processed release v0.2.819.
• apps/api/src/server/routes/session/stop.ts (new): route definition, response schema, tags.
• apps/api/src/server/routes/public-api/session.ts: adds userSession.route('/', stopSessionRouter) (previously absent).
• apps/api/src/server/routes/session/index.ts: removes the old inline handleStopSession//:id/stop registration in favor of the shared router (pure refactor on the internal side, but a net-new capability on the public-api side).
• apps/api/tests/server/publicApiSessionStop.test.ts (new test file added in the same release) exercises this route.

Confidence

High confidence: this is an exact, mechanical addition of a route, method, path parameter, and response schema that can be read directly off the shipped code and its accompanying test — no guessing about wording, positioning, or intent. The new entry mirrors the existing /session/{sessionId}/messages entry's structure and the file's established conventions (indentation, operationId naming, error schema shape, self-hosted URL pattern), so no style drift is introduced. I intentionally did not add a JS SDK code sample for this endpoint since the @tembo-io/sdk package lives outside this repo and I have no evidence of its method name for this route — only the verified cURL/REST contract is documented.

cc @benja

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

      

---

Note

Low Risk
Documentation-only OpenAPI and nav updates with no runtime or security impact.

Overview
Documents the new public POST /session/{sessionId}/stop endpoint in both the hosted and self-hosted API references.

Adds the OpenAPI operation (response schema, 400/404 errors, and cURL sample) to openapi.documented.yml and openapi.self-hosted.yml, and lists it under the Sessions nav group in docs.json for both API tabs.

^{Reviewed by Cursor Bugbot for commit 4165983. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Aug 12, 2026, 1:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[tembo]

Requesting review from @DarrenBaldwin07 who has experience with the following files modified in this PR:

• docs.json
• openapi.documented.yml
• openapi.self-hosted.yml