Widget protocol (reference)

This page is for understanding what the widget does. It is not for building your own client. Turnstile is required, so server-to-server use is not possible. This is not a supported API, and it can change without notice.

The widget talks to api.paperlinkai.com with a small set of requests. This page shows the order of the requests and the shape of the data.

Sequence

Endpoints

Request	Headers	Purpose
`GET /v1/widget/config`	`X-API-Key`	Get the bot name, color, position and Turnstile site key.
`GET /v1/widget/challenge?key=&parent=`	none (the key is in the query)	The Turnstile page that the widget loads in a frame. It sends the token to `parent` with `postMessage`. `parent` must be on your allowed origins.
`POST /v1/widget/sessions`	`X-API-Key`	Start a session with a Turnstile token.
`POST /v1/widget/sessions/:id/refresh`	`X-API-Key`, `X-PL-Resume`	Trade a resume token for new tokens.
`GET /v1/widget/sessions/:id?limit=`	`X-API-Key`, `X-PL-Session`	Load the latest messages.
`POST /v1/widget/sessions/:id/messages`	`X-API-Key`, `X-PL-Session`	Send a question. The reply is a Server-Sent Events stream.
`POST /v1/widget/sessions/:id/messages/:messageId/feedback`	`X-API-Key`, `X-PL-Session`	Send a rating.
`POST /v1/widget/sessions/:id/contact`	`X-API-Key`, `X-PL-Session`	Send the conversation to your support email.

Message request

The body is { "content": "..." }. The content has 1 to 2,000 characters after trimming. The feedback body has a rating of 1 or -1. The optional reason is one of wrong, outdated, not_what_i_asked or other.

Server-Sent Events

The stream sends events in this order: meta, then text many times, then followups, then done. An error event can come at any point. It ends the stream.

text

string

The next piece of the answer text.

followups

string[]

The follow-up questions that the widget shows as chips.

done

string

The id of the answer message.

object[]

The cited pages. Each item has doc and page.

string

cache or rag. The value card is reserved and is not sent today.

boolean

false when the bot could not answer.

object

The contact card data: type is contact, with email and url. It is present when the widget shows your contact card.

error

string

The error code. See the list below.

string

A readable message.

object

The contact card data, when the widget shows your contact card.

Error codes

The error event uses these codes:

REPLY_LIMIT
RATE_LIMITED
MODEL_ERROR
RETRIEVAL_ERROR
INTERNAL
SUBSCRIPTION_INACTIVE

HTTP error envelope

Requests that fail before the stream starts return this JSON. A 429 reply carries the header retry-after: 60.

{
  "error": {
    "code": "ORIGIN_NOT_ALLOWED",
    "message": "This site is not allowed to use this widget. Add it to the bot's allowed origins.",
    "details": null,
    "requestId": "..."
  }
}

string

A stable code in upper case, for example ORIGIN_NOT_ALLOWED.

string

A readable message.

any

Extra data. It is present for some errors only.

string

The request id. Give it to support when you report a problem.

Install the widget with a script tag

Go back to the supported way to add the widget.

Install

Configure

Security

Reference

Widget protocol (reference)

Sequence

Endpoints

Message request

Server-Sent Events

meta

text

followups

done

error

Error codes

HTTP error envelope

Install the widget with a script tag

​Sequence

​Endpoints

​Message request

​Server-Sent Events

​meta

​text

​followups

​done

​error

​Error codes

​HTTP error envelope

Install the widget with a script tag

Sequence

Endpoints

Message request

Server-Sent Events

meta

text

followups

done

error

Error codes

HTTP error envelope