docs(api): surface the run followups endpoint in API & SDK reference

[seemeroland]

Summary

Improves discoverability of the run follow-ups endpoint in the public Oz API & SDK docs.

REMOTE-1889 — a customer building a custom GitHub Actions integration could not find an API to send a follow-up message (the way the Linear/Slack integrations do). The capability is already exposed:

• REST API: POST /agent/runs/{runId}/followups (documented in the Scalar reference at /api).
• SDKs: already generated from warp-server/stainless/stainless.yml (agent.runs.submit_followup), and both OpenAPI specs already define the endpoint and the RunFollowupRequest schema.

The gap was the human-readable overview page, which listed only run/list/get as the "primary endpoints", so the follow-up endpoint was effectively hidden.

Changes

• reference/api-and-sdk/index.mdx
  • Add POST /agent/runs/{runId}/followups (and POST /agent/runs/{runId}/cancel) to the Key Endpoints list, noting it is the same capability the Slack and Linear integrations use, and that it is available in the SDKs (runs.submit_followup).
  • Add RunFollowupRequest to the Models Reference list.
• reference/api-and-sdk/quickstart.mdx
  • Add a Next steps pointer for sending a follow-up to a run.

Notes

• No SDK/stainless.yml or OpenAPI changes were required — the endpoint is already exposed there. This PR is scoped to the remaining docs-discoverability gap called out in the issue.
• Validated with npm run build (337 pages built, no errors).

Testing

• npm run build — succeeds.

Conversation: https://staging.warp.dev/conversation/67551d0d-4dd3-41c8-a959-ec5d77d24221
Run: https://oz.staging.warp.dev/runs/019ea832-5fd9-7656-ad84-5afdeb7f085e

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 9, 2026 6:55pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR updates the API and SDK reference docs so the existing run follow-up endpoint is discoverable from the overview and quickstart pages. I checked the added endpoint references against the local OpenAPI spec; no approved or repository spec context was provided, and I did not find security concerns in the docs-only changes.

Concerns

• The new overview wording can make mode sound like an HTTP query parameter even though RunFollowupRequest defines it as a request-body field.

Verdict

Found: 0 critical, 0 important, 1 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

💡 [SUGGESTION] Avoid calling mode an "optional query" here; RunFollowupRequest defines it as a request-body field, and this wording can read like a URL query parameter.

Suggested change

Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use.

Send a follow-up message to an existing run, the same capability the Slack and Linear integrations use to continue a run. The server routes the message based on the run's current state (queued, running, or ended), so you can steer or continue a run programmatically. A `200` response means the follow-up was accepted; observe the updated state with `GET /agent/runs/{runId}`. The follow-up message and optional `mode` field are described by the `RunFollowupRequest` model.