Start a conversation

Starts a user-owned conversation with its first message. Reuse clientRequestId and the same message to retry. Poll GET /v1/chats/{chatId} for status, messages, citations and steps. Hosted sessions retain app, release and session scope. Unlike answer jobs, chats preserve conversation and support further turns.

POST/v1/chats

betauserworkspace

When to use

Start a conversation that will accept further messages.

For agents

Requires a user session. Reuse the first request ID on retry; poll the returned chat ID. Answer jobs remain one-shot analysis.

Example

typescript

import { PermuteAppClient } from '@permute/sdk/app';

const client = new PermuteAppClient();
const result = await client.chats.create({
  "action": "send_message",
  "clientRequestId": "first_turn",
  "message": "Show the pipeline"
});

Request body

json

{
  "action": "send_message",
  "clientRequestId": "first_turn",
  "message": "Show the pipeline"
}

Response

json

{
  "data": {
    "id": "chat_abcdefghijklmnopqrstuvwx",
    "status": "running",
    "error": null,
    "conversation": [
      {
        "role": "user",
        "content": "Show the pipeline"
      }
    ],
    "traceSteps": []
  }
}