# Stop chat

Source: https://docs.recoupable.dev/api-reference/chat/stop

Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns stopped: false when nothing is in progress.

## POST /api/chat/{chatId}/stop

Full OpenAPI specification: https://docs.recoupable.dev/spec/research.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://docs.recoupable.dev/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Research",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/chat/{chatId}/stop": {
      "post": {
        "operationId": "postChatByChatIdStop",
        "description": "Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account.\n\nThe active slot is released only after cancellation is confirmed. Cancellation failure (502) or termination timeout (504) keeps it occupied; a later stop can retry. A successful no-active stop returns stopped: false.\n\nWhen a workflow is still starting and has no cancellable run ID, Stop returns retryable `503` and retains the active reservation. It does not report `stopped: true`; retry Stop shortly. A local reader abort is not confirmation that server work stopped.\n\nFor readers using `streamLifecycle=explicit-stop-v1`, this authenticated endpoint remains the explicit cancellation path.",
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "chatId",
            "in": "path",
            "required": true,
            "description": "UUID of the chat to stop.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "No active workflow exists (`stopped: false`), or cancellation and terminal status were confirmed (`stopped: true`). A pending start returns 503 instead of successful cancellation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatResponse"
                }
              }
            }
          },
          "400": {
            "description": "chatId is not a valid UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The chat belongs to a different account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Chat not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Session ownership lookup failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Workflow cancellation failed; the active slot remains held.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Workflow start has reserved the chat but has not returned a cancellable run ID. The reservation remains held, and cancellation is not confirmed. Retry Stop shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                },
                "examples": {
                  "pendingStart": {
                    "summary": "Stop requested before the workflow run ID is available",
                    "value": {
                      "status": "error",
                      "error": "Workflow is still starting; retry Stop shortly"
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Workflow did not reach a terminal state before the wait deadline; the active slot remains held.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopChatErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StopChatResponse": {
        "type": "object",
        "required": [
          "success",
          "stopped"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Always true when the request was processed.",
            "example": true
          },
          "stopped": {
            "type": "boolean",
            "description": "True when an in-progress response was cancelled; false when nothing was running.",
            "example": true
          }
        }
      },
      "StopChatErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      }
    }
  }
}
```