API REFERENCE

Start Chat Run

On this page

POST/api/chat/runs

Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive POST /api/chat.

Related endpoints - POST /api/chat — 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} — poll to learn whether the run finished (and if it succeeded). - GET /api/chat/{chatId}/stream — watch the output live by passing the returned chatId.

Authentication

x-api-key in header

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/chat/runs' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "string",
  "messages": [
    {
      "id": "string",
      "role": "user",
      "content": "string"
    }
  ],
  "artistId": "YOUR_ID",
  "model": "openai/gpt-5-mini",
  "trigger_run_id": "run_06g3i0e3logru439uh9e1m8801"
}'

Request body required

Chat generation request

application/json

promptstring

Single text prompt for the assistant. Required if 'messages' is not provided.

messagesarray<UIMessage>

Array of UIMessage objects for context. Required if 'prompt' is not provided.

Item properties

idstring

Unique identifier for the message

rolestring · enum

The role of the message sender

Values: "user", "assistant", "system"

contentstring

The text content of the message

artistIdstring

The unique identifier of the artist (optional)

format: uuid

modelstring

The AI model to use for text generation (optional)

trigger_run_idstring

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.

Responses

202Run 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 (resume the stream) or the chat's persisted messages. Poll GET /api/chat/runs/{runId} for status.

Locationresponse header

Relative URL of the run-status resource for the started run.

application/json

runIdstringrequired

Durable workflow run id for the started generation. Same identifier surfaced as the x-workflow-run-id header on interactive POST /api/chat.

chatIdstringrequired

Chat the run writes its assistant messages to. Use with GET /api/chat/{chatId}/stream to resume the stream, or to fetch the persisted messages.

format: uuid

sessionIdstringrequired

Session (workspace + sandbox) provisioned for the run.

format: uuid

400Bad request - missing required parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

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

{
  "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"
          }
        }
      }
    }
  }
}