Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Stop chat

On this page
POST/api/chat/{chatId}/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. The chat must belong to the authenticated account.

The 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.

When 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.

For readers using streamLifecycle=explicit-stop-v1, this authenticated endpoint remains the explicit cancellation path.

Authentication

x-api-key in header

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/chat/YOUR_CHAT_ID/stop' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://api.recoupable.dev/api/chat/{chatId}/stop'

Parameters

Path parameters

chatIdstringrequired

UUID of the chat to stop.

Responses

200No active workflow exists (stopped: false), or cancellation and terminal status were confirmed (stopped: true). A pending start returns 503 instead of successful cancellation.

application/json

successbooleanrequired

Always true when the request was processed.

Example: true

stoppedbooleanrequired

True when an in-progress response was cancelled; false when nothing was running.

Example: true

400chatId is not a valid UUID

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

401Missing or invalid authentication.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

403The chat belongs to a different account

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

404Chat not found

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

500Session ownership lookup failed.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

502Workflow cancellation failed; the active slot remains held.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

503Workflow 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.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

Stop requested before the workflow run ID is available

pendingStart
{
  "status": "error",
  "error": "Workflow is still starting; retry Stop shortly"
}

504Workflow did not reach a terminal state before the wait deadline; the active slot remains held.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json
View operation source
json
{
  "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"
          }
        }
      }
    }
  }
}