# Start Chat Run

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

Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).

## POST /api/chat/runs

Full OpenAPI specification: https://recoupable.dev/docs/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://recoupable.dev/docs/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/runs": {
      "post": {
        "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).\n\n**Related endpoints**\n- [`POST /api/chat`](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.",
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "requestBody": {
          "description": "Chat generation request",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Run accepted. A durable workflow run was started; `runId` identifies it. `chatId` / `sessionId` identify the persisted output — read the result via [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) (resume the stream) or the chat's persisted messages. Poll [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) for status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatGenerateAcceptedResponse"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "Relative URL of the run-status resource for the started run.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "example": "/api/chat/runs/wrun_01KVWZNM82NA7XKNEWWHG8VPHJ"
              }
            }
          },
          "400": {
            "description": "Bad request - missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatGenerateErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChatGenerateRequest": {
        "type": "object",
        "description": "Request body for chat generation. Exactly one of 'prompt' or 'messages' must be provided.",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Single text prompt for the assistant. Required if 'messages' is not provided."
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UIMessage"
            },
            "description": "Array of UIMessage objects for context. Required if 'prompt' is not provided."
          },
          "artistId": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier of the artist (optional)"
          },
          "model": {
            "type": "string",
            "description": "The AI model to use for text generation (optional)",
            "example": "openai/gpt-5-mini"
          },
          "trigger_run_id": {
            "type": "string",
            "description": "Optional. When the run is kicked off by a Trigger.dev scheduled task, the Trigger run id (`run_...`). The started workflow's `{ sessionId, chatId, workflowRunId }` are written to that Trigger run's metadata so the scheduled run can be traced to the chat that did the work.",
            "example": "run_06g3i0e3logru439uh9e1m8801"
          }
        }
      },
      "ChatGenerateAcceptedResponse": {
        "type": "object",
        "required": [
          "runId",
          "chatId",
          "sessionId"
        ],
        "description": "Confirmation that an asynchronous chat-generation run has been started on the durable agent workflow.",
        "properties": {
          "runId": {
            "type": "string",
            "description": "Durable workflow run id for the started generation. Same identifier surfaced as the `x-workflow-run-id` header on interactive [POST /api/chat](/api-reference/chat/workflow).",
            "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ"
          },
          "chatId": {
            "type": "string",
            "format": "uuid",
            "description": "Chat the run writes its assistant messages to. Use with [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) to resume the stream, or to fetch the persisted messages.",
            "example": "24830c6c-76d8-43be-ae22-1dfd545421ab"
          },
          "sessionId": {
            "type": "string",
            "format": "uuid",
            "description": "Session (workspace + sandbox) provisioned for the run.",
            "example": "fa9c1516-35f0-4efd-a62c-01af26324e72"
          }
        }
      },
      "ChatGenerateErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "UIMessage": {
        "type": "object",
        "description": "A message in the chat conversation. See https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message for details.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the message"
          },
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant",
              "system"
            ],
            "description": "The role of the message sender"
          },
          "content": {
            "type": "string",
            "description": "The text content of the message"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      }
    }
  }
}
```