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

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 '{
  "messages": [
    {
      "id": "user-1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Summarize my next release."
        }
      ]
    }
  ]
}'

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/runs' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {
      "id": "user-1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Summarize my next release."
        }
      ]
    }
  ]
}'

Request body required

Chat generation request

application/json

promptstring

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

minLength: 1

messagesarray<UIMessage>

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

minItems: 1

Item properties for messages
idstringrequired
rolestring · enumrequired

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

metadataany
partsarray<object>required

SDK discriminated parts: text (text), file (mediaType and url), reasoning, supported tool and data-* parts. Each must satisfy the installed AI SDK schema; a type field alone is insufficient.

Example: [{"type":"text","text":"Summarize my next release."}]

minItems: 1

Item properties for parts
typestringrequired
Additional properties

Additional keys are allowed.

artistIdstring

The unique identifier of the artist (optional)

format: uuid

modelstring

The AI model to use for text generation (optional)

Example: "openai/gpt-5-mini"

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.

Example: "run_06g3i0e3logru439uh9e1m8801"

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.

Example: "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ"

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.

Example: "24830c6c-76d8-43be-ae22-1dfd545421ab"

format: uuid

sessionIdstringrequired

Session (workspace + sandbox) provisioned for the run.

Example: "fa9c1516-35f0-4efd-a62c-01af26324e72"

format: uuid

400Bad request - missing required parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Validation error describing why the headless request was rejected.

missing_fieldsarray<string>

Optional validation path when available; a general request error can omit it.

Item properties for missing_fields

string

Full specification

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

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