Skip to content
Docs

Start a conversation

POST
/api/workspaces/{ws}/assistant/conversations

With onboarding: true, it starts with the onboarding's greeting and quick replies.

Authorization

session
cookiebetter-auth.session_token<token>

Set by POST /api/auth/sign-in/email.

Path Parameters

ws*string

The workspace id (from GET /api/me).

Request Body

application/json
  1. body
onboarding?boolean

Response Body

The conversation and its opening messages.

application/json
Example Request
curl -X POST 'https://app.useroster.work/api/workspaces/string/assistant/conversations' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "conversation": {    "id": "0b8e…",    "title": "",    "onboarding": true  },  "messages": [    {      "id": "c1…",      "role": "assistant",      "content": "Hi Ada, I'm Front Desk…"    }  ]}

Finish or skip the onboarding PUT

Whatever was set up so far stays. `conversationId` is the onboarding conversation, kept for later.

A conversation GET

Its messages in order: yours, the assistant's (with its tool calls), each tool's compact answer and things you did in a card (`event`). `cards` are what the app shows inline: `choices`, `connect`, `hire`, `confirm` and `step`.