# API endpoints

> Widget API endpoints: sessions, messages with streaming, history, leads and widget settings.

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:

```text
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

```text
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](/en/docs/user-context/)

Response:

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

## Send a message

```text
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

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

Returns the session's messages:

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

## Save a lead

```text
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.

```json
{
  "session_id": "session_xyz789",
  "lead_data": {
    "lead_email": "anna@company.com",
    "lead_phone": "+44 7700 900000",
    "lead_first_name": "Anna",
    "lead_last_name": "Smith"
  }
}
```

## Widget settings

```text
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.

```json
{
  "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"
}
```