> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Chat Run

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

**Related endpoints**
- [`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).
- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).
- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.



## OpenAPI

````yaml post /api/chat/runs
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
security: []
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).


        **Related endpoints**

        - [`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).

        - [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — poll
        to learn **whether** the run finished (and if it succeeded).

        - [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream)
        — **watch the output live** by passing the returned `chatId`.
      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'
      security:
        - apiKeyAuth: []
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
    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).

````