---
title: "Submit a follow-up message to the run behind a conversation"
method: POST
path: "/agent/conversations/{conversation_id}/followups"
tags: ["Agents"]
---

# Submit a follow-up message to the run behind a conversation

`POST /agent/conversations/{conversation_id}/followups`

## Request

- Base URL: `https://app.warp.dev/api/v1`
- URL: `https://app.warp.dev/api/v1/agent/conversations/{conversation_id}/followups`
- Auth: HTTP bearer

The same operation as `POST /agent/runs/{runId}/followups`, targeted
by the conversation the run is serving rather than the run itself.

`attachments` must name ids prepared through
`POST /agent/conversations/{conversation_id}/attachments/prepare` (or
the run-keyed prepare) for the run that is newest at that time. If a
new run appears for the conversation between prepare and follow-up,
the follow-up resolves to the new run and answers 422
`unknown_attachment`; prepare again. A handoff is a new execution of
the same run and does not have this problem.

`mode` only takes effect when the follow-up is queued ahead of the run
starting or starts a new execution; a follow-up injected into a live
session runs in the session's current mode.

## Path parameters

- `conversation_id` string, uuid, required

## Request body

- RunFollowupRequest: Request body for submitting a follow-up message to an existing run.
  - `message` string: The follow-up message to send to the run. May be empty when `attachments` is non-empty.
  - `mode` 'normal' | 'plan' | 'orchestrate': Query mode for an agent run. - normal: Standard user query (default). - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution. - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
  - `attachments` RunFollowupAttachment[]: Files to deliver with the message, at most 25. Each entry must name an attachment previously prepared for this run through `POST /agent/runs/{runId}/attachments/prepare` and uploaded to its upload target; an unknown `attachment_id` is rejected with 422. Files are only materialized for the agent on the Oz harness; other harnesses receive a notice naming the files.
    - `attachment_id` string, required: The `attachment_id` (a UUID) returned by the attachment prepare endpoint for this run.
    - `file_name` string: Optional display name shown to the agent in place of the name recorded when the attachment was prepared. The stored object is unaffected.

## Response `200`

Follow-up accepted

- ConversationFollowupResponse: Acknowledgement of a follow-up accepted through a conversation-keyed route: the run-keyed acknowledgement plus the run it was delivered to.
  - `followup_id` string, nullable, required: Identifier of the durable follow-up record, or null when the outcome did not create one (`queued_prompt`).
  - `outcome` 'live_session' | 'queued_prompt' | 'handoff_execution' | 'queue_pending', required: How an accepted follow-up was routed. - live_session: the message was handed to the running session. This means the session-sharing service accepted it, not that the agent has started on it; observe the session's event stream for the new request. - queued_prompt: the run had not started yet, so the message was appended to its initial prompt. - handoff_execution: the previous execution had ended, so a new execution of the same run was created to continue the conversation. - queue_pending: the message is durably queued and will be delivered once the run can accept it.
  - `run_id` string, required: The run the conversation resolved to.

## Other responses

- `400`: Invalid conversation ID or malformed payload
- `401`: Authentication required
- `403`: No permission to view the conversation or to follow up on its run
- `404`: Conversation not found
- `409`: The conversation has no run to steer (`reason: no_run`), for example a purely local, cloud-synced conversation.
- `422`: An `attachment_id` is not recorded on the resolved run (`reason: unknown_attachment`), or more than 25 attachments were named (`reason: too_many_attachments`).
- `500`: Internal server error

## Changes

- **2026-10-13** `96d1e59a65c5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/agent/conversations/:conversation_id/followups/post.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)