Build a custom frontend

Use Webless REST endpoints and WebSocket streaming to power your own search UI.

Generate one sessionId per browser session and one requestId per user action. Reuse both values across the coordinated calls for that action.

Environments

Environment	REST base URL	WebSocket URL
Staging	https://d2wanlnzrkmzyb.cloudfront.net	wss://d2wanlnzrkmzyb.cloudfront.net/ws
Production	https://api.webless.ai	wss://api.webless.ai/ws

Use ws:// only for local development.

Request flow

Orchestrate the full experience

1. Create identifiers

   Create a sessionId once per user session. Create a new requestId for each query or action.

2. Fetch tiles with /post_query

   Call POST /post_query to fetch the top content tiles for the query. Keep the same sessionId and requestId you will use everywhere else.

3. Stream the summary over WebSocket

   Open /ws and send the get_summary_with_cache action. Append summary_part chunks as they arrive, then finalize the UI when you receive summary_complete.

4. Fetch a CTA and suggestions in parallel

   Call POST /dynamic_cta and POST /get_suggestions with the same IDs so Webless can correlate the entire experience.

WebSocket request

{
  "action": "get_summary_with_cache",
  "params": {
    "query": "What does Webless do?",
    "company": "YOUR_COMPANY",
    "requestId": "YOUR_REQUEST_ID",
    "sessionId": "YOUR_SESSION_ID",
    "markdown": true,
    "number_of_tiles": 6,
    "summary_word_limit": 120
  }
}

WebSocket events

Event	Meaning
summary_part	A streamed chunk of summary text
summary_tiles	Tile IDs emitted near completion
summary_complete	The stream finished successfully
error	The request failed

JavaScript example

const sessionId = getOrCreateSessionId();
const requestId = crypto.randomUUID();

const ws = new WebSocket("wss://api.webless.ai/ws");

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      action: "get_summary_with_cache",
      params: {
        query: "What does Webless do?",
        company: "YOUR_COMPANY",
        requestId,
        sessionId,
        number_of_tiles: 6,
        markdown: true,
        summary_word_limit: 120
      }
    })
  );
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.event === "summary_part") {
    appendSummary(message.data.summary_part);
  } else if (message.event === "summary_tiles") {
    renderTileIds(message.data.summary_tiles);
  } else if (message.event === "summary_complete") {
    finalizeExperience();
  } else if (message.event === "error") {
    console.error(message.data?.message);
  }
};

Use the pages in API reference for request and response schemas. Use this guide for orchestration and WebSocket behavior.