Agents

Cancel an in-flight agent chat stream

Changed on

Cooperatively stop a POST /agents/{agentKey}/conversations/stream or .../messages/stream run that is still generating, using the runId sent when that stream started.

Same synchronous JSON ack contract as the assistant POST /conversations/{conversationId}/cancel — both forward to the same backend cancellation endpoint, since the run registry is keyed by runId alone.

cancelled reports whether a stop request was issued, not whether a run was actually stopped. With the default shared (key-value backed) run registry, a runId that the answering worker does not hold is published for whichever worker owns it, and the answer is { cancelled: true } even when the run already finished or was never registered. { cancelled: false } is returned for such a runId only when the registry is in-process, or when the stop request could not be published.

runId must belong to a run started on THIS conversationId — a runId that exists but was registered under a different conversation (even one owned by the same caller) is rejected with 403, same as a runId owned by a different user/org.

post/agents/{agentKey}/conversations/{conversationId}/cancel

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/agents/{agentKey}/conversations/{conversationId}/cancel
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: /api/v1/oauth2/authorize
      Client credentials
      Token URL: /api/v1/oauth2/token scopes: agent:execute

Path parameters

agentKeystring required

Stable key identifying the agent that owns this conversation.

conversationIdstring objectId required

ID of the agent conversation to cancel a run for.

Request body

runIdstring uuid required

The runId sent when the stream was started. Anything but a UUID string is refused with VALIDATION_ERROR.

Response

Cancellation requested, or the run had already finished.

cancelledboolean required

true when a stop request was issued for runId; false when the run is unknown to an in-process registry or the request could not be published.

Changes

    • breaking

      added the pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ to the request property

    • info

      added the media type application/x-www-form-urlencoded to the request body

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      the response property became required for the status

    • info

      endpoint added