widgets

List widgets

The widgets of the workspace, newest first, each with its settings, limits, the snippets to install it and this month's conversations, answers and credits. A widget is a chat box that shows one of your assistants to anonymous visitors on a website. A technical identity limited to some assistants sees only their widgets.

GET/v1/widgets

Request

curl --request GET \
  --url 'https://api.lookio.app/v1/widgets' \
  --header 'Authorization: <api-key>'

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.lookio.app/v1/widgets");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
]);
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.lookio.app/v1/widgets", nil)
  req.Header.Set("Authorization", "<api-key>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.lookio.app/v1/widgets"))
    .header("Authorization", "<api-key>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.lookio.app/v1/widgets")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "<api-key>"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "data": [
    {
      "id": "wdg_xpatjpwt22fu",
      "name": "Docs chat",
      "assistant_id": "ast_66xcnwtzj8vt",
      "assistant_name": "Support",
      "mode": "flash",
      "status": "live",
      "allowed_domains": [
        "docs.acme.com"
      ],
      "settings": {
        "theme": "auto",
        "accent": "#4F46E5",
        "radius": "medium",
        "bubbles": "corners",
        "position": "bottom-right",
        "launcher": "bubble",
        "launcher_label": "Ask AI",
        "title": "",
        "greeting": "Hi! Ask me anything, I answer from our documentation.",
        "placeholder": "Ask a question…",
        "suggestions": [],
        "disclaimer": "AI answers can be wrong.",
        "language": "auto",
        "sources": "numbered",
        "memory": true,
        "visitor_history": true,
        "feedback": true,
        "branding": true,
        "hosted_page": true
      },
      "limits": {
        "per_visitor_hour": 40,
        "per_visitor_day": 150,
        "monthly_credits": null
      },
      "snippets": {
        "bubble": "<script src=\"https://widget.lookio.app/v1/widget.js\" data-lookio-widget=\"wdg_j36h6kb8tyng\" async></script>",
        "embed": "<div data-lookio-embed=\"wdg_j36h6kb8tyng\" style=\"height: 600px\"></div>\n<script src=\"https://widget.lookio.app/v1/widget.js\" async></script>",
        "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng",
        "iframe": "<iframe src=\"https://widget.lookio.app/w/wdg_j36h6kb8tyng?embed=1\" style=\"width: 100%; height: 600px; border: 0\" title=\"Chat\"></iframe>"
      },
      "stats": {
        "conversations": 12,
        "answers": 31,
        "credits": 930
      },
      "created_via": "api",
      "created_at": "2026-10-12T09:30:00.000Z",
      "updated_at": "2026-10-12T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_01K9X7M2Q4"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

Requires assistants:read.

A widget is a chat box that shows one of your assistants to anonymous visitors on a website. See the Widget guide for what visitors see.

Each widget comes with its snippets and with stats for the current calendar month (UTC): conversations, answers and the credits they cost. An API key limited to some assistants sees only their widgets. A widget whose assistant was deleted shows assistant_name as null and answers nothing until you point it at another.

Authorizations

Authorizationbearerin headerrequired

Response

application/json

List widgets

dataobject[]required

Show child attributes

data.idstringrequiredpattern: ^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$

data.namestringrequired

data.assistant_idstringrequired

data.assistant_namestringnullrequired

Null when the assistant was deleted: the widget answers nothing until you point it at another.

data.modeenum<string>requiredone of: eco, flash, deep

data.statusenum<string>requiredone of: live, paused

live answers visitors; paused shows nothing and answers nothing, until set live again.

data.allowed_domainsstring[]required

data.settingsobjectrequired

Show child attributes

data.settings.themeenum<string>requireddefault: autoone of: light, dark, auto

light, dark, or auto to follow the visitor's system.

data.settings.accentstringrequireddefault: #4F46E5pattern: ^#[0-9a-fA-F]{6}$

The brand colour of the launcher and the buttons, as #RRGGBB.

data.settings.radiusenum<string>requireddefault: mediumone of: none, small, medium, large

How round the corners are: none, small, medium or large.

data.settings.bubblesenum<string>requireddefault: cornersone of: corners, round

The shape of the visitor's message bubbles and the suggestion chips: corners (default) follows radius, round makes them fully round whatever the corners are. Omit it to leave it as it is.

data.settings.positionenum<string>requireddefault: bottom-rightone of: bottom-right, bottom-left

Which corner of the page the bubble sits in: bottom-right or bottom-left.

data.settings.launcherenum<string>requireddefault: bubbleone of: bubble, pill, bar

bubble: a round button in a corner. pill: a button with launcher_label. bar: a bar centered at the bottom of the page, showing the placeholder, that opens the chat in the middle of the screen (position does not apply).

data.settings.launcher_labelstringrequireddefault: Ask AIlength: ≤ 40 chars

The text of the pill launcher, up to 40 characters.

data.settings.launcher_iconenum<string>requireddefault: chatone of: chat, message, help, sparkles, bot, search, book, bulb, bolt, heart, star, support

The launcher's icon: chat (default), message, help, sparkles, bot, search, book, bulb, bolt, heart, star or support.

data.settings.launcher_sizeenum<string>requireddefault: mediumone of: small, medium, large

The launcher's size, whatever its style: small, medium (default) or large.

data.settings.bar_iconbooleanrequireddefault: true

The bar launcher: show the icon at its start (default). Off: a plain field.

data.settings.bar_translucentbooleanrequireddefault: false

The bar launcher: see-through, with the page blurred behind it. Off (default): a solid bar.

data.settings.launcher_imagestring | nullrequireddefault: null

Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with PUT /v1/widgets/{id}/images/launcher or in the app. Null: the icon.

data.settings.faviconstring | nullrequireddefault: null

Paid plans, read-only: the name of the hosted page's favicon, set with PUT /v1/widgets/{id}/images/favicon or in the app. Null: a favicon drawn from the widget's colour and icon.

data.settings.header_iconenum<string>requireddefault: sparklesone of: chat, message, help, sparkles, bot, search, book, bulb, bolt, heart, star, support, none

The avatar in the chat's header, apart from the launcher's icon: sparkles (default), chat, message, help, bot, search, book, bulb, bolt, heart, star or support; none shows no avatar at all.

data.settings.header_imagestring | nullrequireddefault: null

Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with PUT /v1/widgets/{id}/images/header or in the app. Null: the header icon.

data.settings.titlestringrequireddefault: ""length: ≤ 60 chars

The chat's title, up to 60 characters. Empty means the assistant's name.

data.settings.subtitlestringrequireddefault: ""length: ≤ 80 chars

A line under the chat's title, up to 80 characters, like Available 24/7. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.

data.settings.greetingstringrequireddefault: Hi! Ask me anything, I answer from our documentation.length: ≤ 500 chars

The first message the visitor sees, up to 500 characters.

data.settings.placeholderstringrequireddefault: Ask a question…length: ≤ 80 chars

The hint in the question box, up to 80 characters.

data.settings.suggestionsstring[]requireddefault: []items: ≤ 4 items

Up to 4 example questions (120 characters each) shown before the first question.

data.settings.disclaimerstringrequireddefault: AI answers can be wrong.length: ≤ 200 chars

The small print under the chat, up to 200 characters. Empty hides it.

data.settings.languageenum<string>requireddefault: autoone of: auto, en, fr, de, es, it, pt

The language of the widget's own words (buttons, notices): auto follows the visitor, or en, fr, de, es, it, pt. Answers always follow the visitor's language.

data.settings.sourcesenum<string>requireddefault: numberedone of: numbered, numbered_no_links, inline_links, none

How answers show their sources: numbered ([1] markers and a source list with links to web pages), numbered_no_links (the same without any address), inline_links (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or none.

data.settings.memorybooleanrequireddefault: true

Follow-up questions see the conversation so far.

data.settings.visitor_historybooleanrequireddefault: true

Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.

data.settings.feedbackbooleanrequireddefault: true

Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: GET /v1/logs/conversations?widget_id=…&rating=down lists the conversations where visitors were not satisfied.

data.settings.brandingbooleanrequireddefault: true

Show "Powered by Lookio". Only paid plans may turn it off.

data.settings.bubblebooleanrequireddefault: true

The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.

data.settings.embedbooleanrequireddefault: false

The in-page format: the chat inside a container of your page (snippets.embed, or snippets.iframe). Off by default; off, the frame answers 404.

data.settings.hosted_pagebooleanrequireddefault: false

The hosted page format: a full-page chat at snippets.hosted, to link to. Off by default; off, the page answers 404.

data.limitsobjectrequired

Show child attributes

data.limits.monthly_credits_enabledbooleanrequireddefault: false

data.limits.per_visitor_hourintegerrequireddefault: 40range: 1–500

Questions one visitor may ask per hour, 1 to 500.

data.limits.per_visitor_dayintegerrequireddefault: 150range: 1–2000

Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.

data.limits.monthly_creditsinteger | nullrequireddefault: null

Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.

data.snippetsobjectrequired

Show child attributes

data.snippets.bubblestringrequired

A <script> tag: a launcher in a corner of the page opens the chat. Paste it before </body>.

data.snippets.embedstringrequired

A <div> and the script: the chat fills the div, where you put it. Give the div a height.

data.snippets.hostedstringrequired

A link to a full-page chat. Needs no website; can be turned off with settings.hosted_page.

data.snippets.iframestringrequired

A raw <iframe> for builders that refuse scripts (Notion, some CMS).

data.statsobjectrequired

This calendar month, UTC.

Show child attributes

data.stats.conversationsintegerrequired

data.stats.answersintegerrequired

data.stats.creditsintegerrequired

data.created_viastringnullrequired

data.created_atstringrequired

data.updated_atstringrequired

has_morebooleanrequired

True when another page follows: pass next_cursor back as cursor.

next_cursorstringnullrequired

Pass it back unchanged as cursor. Null on the last page.

request_idstringrequired

List widgets

Authorizations

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown