widgets

Create a widget

Creates a widget for an assistant and returns it with its snippets: paste snippets.bubble before </body> for a launcher, snippets.embed where the chat should sit, link to snippets.hosted for a full page, or use snippets.iframe where scripts are refused. Only the bubble is on by default: snippets.embed and snippets.iframe work once settings.embed is true, snippets.hosted once settings.hosted_page is true; a format that is off answers 404. Add the websites that show it to allowed_domains: the browser refuses the bubble and the embed on any site not listed. Visitors' answers are charged to this workspace in the widget's mode; limits caps them per visitor and per month. Costs no credits itself.

POST/v1/widgets

Request

curl --request POST \
  --url 'https://api.lookio.app/v1/widgets' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "assistant_id": "<string>"
}'

import json
import requests

url = "https://api.lookio.app/v1/widgets"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"assistant_id\":\"<string>\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.lookio.app/v1/widgets", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "assistant_id": "<string>"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.lookio.app/v1/widgets");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"assistant_id\":\"<string>\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

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

package main

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

func main() {
  req, _ := http.NewRequest("POST", "https://api.lookio.app/v1/widgets", bytes.NewBuffer([]byte("{\"assistant_id\":\"<string>\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  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>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"assistant_id\":\"<string>\"}"))
    .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::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"assistant_id\":\"<string>\"}"

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"
  },
  "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>"
}

{
  "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:write.

Creating a widget costs no credits. Each visitor question that reaches the model spends the widget’s mode price (flash by default, 30 credits), whether or not Lookio finds an answer. Say so to whoever sets it up, and set limits to cap the spending.

Allowed domains. List the websites that show the widget in allowed_domains, for example docs.acme.com. acme.com also covers www.acme.com, and *.acme.com covers every subdomain. The browser refuses the bubble and the embed on any site not listed. With no domain, nothing shows on any site; only the hosted page works, once you turn it on.
Formats. Each format is on or off with a setting: settings.bubble (on by default), settings.embed (off) and settings.hosted_page (off). A new widget starts with the chat bubble only. A format that is off does not exist: the loader script draws no launcher, and the in-page frame and the hosted page answer 404. snippets.iframe belongs to the embed format.
Limits. By default a visitor may ask 20 questions per hour and 60 per day, and the widget may spend 3,000 credits per calendar month (UTC). Set limits.monthly_credits to null for no ceiling beyond the workspace’s balance. See Access and limits.
Sources. settings.sources is numbered (the default), numbered_no_links, inline_links or none. See Appearance.
Snippets. The response holds the code to install it: snippets.bubble before </body> for a launcher, snippets.embed where the chat should sit, snippets.hosted for a full page and snippets.iframe where scripts are refused. See Install a widget.

The widget is live as soon as it exists. Send an Idempotency-Key header so a retried request does not create two widgets.

Authorizations

Authorizationbearerin headerrequired

Header parameters

Idempotency-Keystringlength: 1–255 chars

A unique key for this request, such as a UUID, 1 to 255 visible ASCII characters. Send the same key when you retry: the first response is returned (with Idempotent-Replayed: true) instead of running the request again, for 24 hours, per credential. The same key on a different request is a 409 conflict. A streamed answer is not recorded.

Body

application/jsonrequired

assistant_idstringrequiredpattern: ^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$

The assistant the widget speaks for. A technical identity limited to some assistants can only pick one of them.

namestringlength: 1–120 chars

1 to 120 characters. Defaults to the assistant's name followed by widget.

modeenum<string>one of: eco, flash, deep

The query mode every answer of this widget uses, so what it costs per answer (Eco 10, Flash 30 credits (the default), Deep 80). Default flash.

statusenum<string>one of: live, paused

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

allowed_domainsstring[]items: ≤ 50 items

The websites allowed to show the widget, as hosts (docs.acme.com) or *.acme.com for all subdomains (which also covers acme.com). Scheme, path and port are removed. The browser refuses to show the bubble and the embed on any other site, so a widget with no domain shows nowhere (the hosted page still works). Replaces the previous list.

settingsobject

Appearance, words and behaviour. Every field is optional and has a default.

Show child attributes

settings.themeenum<string>one of: light, dark, auto

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

settings.accentstringpattern: ^#[0-9a-fA-F]{6}$

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

settings.radiusenum<string>one of: none, small, medium, large

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

settings.bubblesenum<string>one 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.

settings.positionenum<string>one of: bottom-right, bottom-left

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

settings.launcherenum<string>one 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).

settings.launcher_labelstringlength: ≤ 40 chars

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

settings.launcher_iconenum<string>one 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.

settings.launcher_sizeenum<string>one of: small, medium, large

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

settings.bar_iconboolean

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

settings.bar_translucentboolean

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

settings.header_iconenum<string>one 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.

settings.titlestringlength: ≤ 60 chars

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

settings.subtitlestringlength: ≤ 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.

settings.greetingstringlength: ≤ 500 chars

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

settings.placeholderstringlength: ≤ 80 chars

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

settings.suggestionsstring[]items: ≤ 4 items

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

settings.disclaimerstringlength: ≤ 200 chars

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

settings.languageenum<string>one 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.

settings.sourcesenum<string>one 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.

settings.memoryboolean

Follow-up questions see the conversation so far.

settings.visitor_historyboolean

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.

settings.feedbackboolean

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.

settings.brandingboolean

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

settings.bubbleboolean

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

settings.embedboolean

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.

settings.hosted_pageboolean

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

limitsobject

Spending and abuse limits. Every field is optional and has a default.

Show child attributes

limits.monthly_credits_enabledboolean

limits.per_visitor_hourintegerrange: 1–500

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

limits.per_visitor_dayintegerrange: 1–2000

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

limits.monthly_creditsinteger | 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.

Response

application/json

Create a widget

dataobjectrequired

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

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

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

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

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

request_idstringrequired

Create a widget

Authorizations

Header parameters

Body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown