Skip to main content
POST
/
api
/
chat
/
runs
cURL
curl --request POST \
  --url https://api.recoupable.com/api/chat/runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "prompt": "<string>",
  "messages": [
    {
      "id": "<string>",
      "content": "<string>"
    }
  ],
  "artistId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model": "openai/gpt-5-mini"
}
'
{
  "runId": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ",
  "chatId": "24830c6c-76d8-43be-ae22-1dfd545421ab",
  "sessionId": "fa9c1516-35f0-4efd-a62c-01af26324e72"
}

Authorizations

​
x-api-key
string
header
required

Your Recoup API key. Learn more.

Body

application/json

Chat generation request

Request body for chat generation. Exactly one of 'prompt' or 'messages' must be provided.

​
prompt
string

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

​
messages
object[]

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

​
artistId
string<uuid>

The unique identifier of the artist (optional)

​
model
string

The AI model to use for text generation (optional)

Example:

"openai/gpt-5-mini"

Response

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

Confirmation that an asynchronous chat-generation run has been started on the durable agent workflow.

​
runId
string
required

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"

​
chatId
string<uuid>
required

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"

​
sessionId
string<uuid>
required

Session (workspace + sandbox) provisioned for the run.

Example:

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