The widget API lets you build your own chat interface on the ProseCaptain assistant. The widget itself uses the same endpoints.

Base URL: https://widget-api.prosecaptain.com/api/v2/widget

Authentication

Pass the widget token in the header:

Authorization: Bearer YOUR_TOKEN

You can also send it as a ?token= parameter. Point to a specific widget with widget_id (in the query or the request body).

Create a chat session

POST https://widget-api.prosecaptain.com/api/v2/widget/thread

Creates a session and returns its id and the history with the welcome message.

Request body (JSON, all fields optional):

  • widget_id: widget id
  • session_id: an existing session to resume
  • context: user context

Response:

{
  "session_id": "session_xyz789",
  "history": [
    { "role": "assistant", "content": "Hello! How can I help?", "timestamp": "2026-10-19T09:00:00Z" }
  ]
}

Send a message

POST https://widget-api.prosecaptain.com/api/v2/widget/message

Sends the user’s message and returns the assistant’s answer.

Request body (JSON):

  • session_id (required): session id
  • message (required): message text, up to 4000 characters
  • widget_id: widget id
  • page_context: context of the page the user is on
  • stream: true to receive the answer as a stream

With stream: true the answer arrives as Server-Sent Events: delta events with the next pieces of text, status with progress, and finally done with the full answer, or error.

Chat history

GET https://widget-api.prosecaptain.com/api/v2/widget/chat-history?session_id=SESSION_ID

Returns the session’s messages:

{
  "messages": [
    { "role": "user", "content": "How long does onboarding take?" },
    { "role": "assistant", "content": "Usually one day…" }
  ]
}

Save a lead

POST https://widget-api.prosecaptain.com/api/v2/widget/save-lead

Saves contact details from the conversation. An email or a phone number (7–15 digits) is required.

{
  "session_id": "session_xyz789",
  "lead_data": {
    "lead_email": "[email protected]",
    "lead_phone": "+44 7700 900000",
    "lead_first_name": "Anna",
    "lead_last_name": "Smith"
  }
}

Widget settings

GET https://widget-api.prosecaptain.com/api/v2/widget/workspace?widget_id=WIDGET_ID

Returns the widget settings you need to build an interface: name, welcome message, title, subtitle, suggested questions, colours and language.

{
  "name": "Your company",
  "welcome_message": "Hello! How can I help?",
  "widget_title": "Got a question?",
  "widget_subtitle": "We answer right away",
  "widget_questions": [{ "question": "How long does onboarding take?", "prompt": "How long does onboarding take?" }],
  "widget_color": "#63AD61",
  "widget_language": "en-us"
}