Chat widget

The embeddable chat widget's appearance.

Base URL https://futuresmart.ai/database-agent/api · every request sends X-API-Key. Samples read the key from DATABASE_AGENT_API_KEY. All endpoints

Retrieve Widget Settings

GET/v1/agents/{agent_id}/widget/settings

Get the agent's widget settings

Authenticated callers get the full record. Anonymous callers are allowed only when the agent has opted this surface in (is_public, or fullscreen_is_public with ?from_full_screen=true) and their Origin matches the matching allowlist; they receive display fields only.

An agent that has never been configured returns the documented defaults rather than 404.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Response · 200

Name	Type	Description
`widget_settings`required	`WidgetSettings`	The widget's appearance. Owner/timestamp fields are absent for anonymous callers — see `PUBLIC_FIELDS` in `api/v1/utils/widgets_helper.py`.
`↳ heading`	`string \| null`
`↳ sub_heading`	`string \| null`
`↳ greet_message`	`string \| null`
`↳ color`	`string \| null`
`↳ show_sources`	`boolean \| null`
`↳ widget_icon`	`string \| null`
`↳ widget_avatar`	`string \| null`
`↳ user_id`	`string \| null`	Owner; omitted for public callers
`↳ created_at`	`string \| null`	Omitted for public callers
`↳ updated_at`	`string \| null`	Omitted for public callers

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/widget/settings",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/widget/settings`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/widget/settings" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Response shape (200)

JSON

{
  "widget_settings": {}
}

Save Widget Settings

POST/v1/agents/{agent_id}/widget/settings

Create or update the agent's widget settings

Multipart. Every field is optional and only what is sent is written, so saving one field leaves the rest untouched. An uploaded file takes precedence over the matching _url.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Request body · multipart/form-data (optional)

Name	Type	Description
`heading`	`string \| null`
`sub_heading`	`string \| null`
`greet_message`	`string \| null`
`color`	`string \| null`
`show_sources`	`boolean \| null`
`widget_icon`	`string \| null`
`widget_avatar`	`string \| null`
`widget_icon_url`	`string \| null`
`widget_avatar_url`	`string \| null`

Response · 200

Name	Type	Description
`message`required	`string`
`widget_settings`required	`WidgetSettings`	The widget's appearance. Owner/timestamp fields are absent for anonymous callers — see `PUBLIC_FIELDS` in `api/v1/utils/widgets_helper.py`.
`↳ heading`	`string \| null`
`↳ sub_heading`	`string \| null`
`↳ greet_message`	`string \| null`
`↳ color`	`string \| null`
`↳ show_sources`	`boolean \| null`
`↳ widget_icon`	`string \| null`
`↳ widget_avatar`	`string \| null`
`↳ user_id`	`string \| null`	Owner; omitted for public callers
`↳ created_at`	`string \| null`	Omitted for public callers
`↳ updated_at`	`string \| null`	Omitted for public callers

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.post(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/widget/settings",
    headers={"X-API-Key": API_KEY},
    data={"heading": "<heading>", "sub_heading": "<sub_heading>", "greet_message": "<greet_message>", "color": "<color>", "show_sources": "<show_sources>", "widget_icon": "<widget_icon>", "widget_avatar": "<widget_avatar>", "widget_icon_url": "<widget_icon_url>", "widget_avatar_url": "<widget_avatar_url>"},
    timeout=120,
)
r.raise_for_status()
print(r.json())

import { readFile } from "node:fs/promises";

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const form = new FormData();
form.append("heading", "<heading>");
form.append("sub_heading", "<sub_heading>");
form.append("greet_message", "<greet_message>");
form.append("color", "<color>");
form.append("show_sources", "<show_sources>");
form.append("widget_icon", "<widget_icon>");
form.append("widget_avatar", "<widget_avatar>");
form.append("widget_icon_url", "<widget_icon_url>");
form.append("widget_avatar_url", "<widget_avatar_url>");

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/widget/settings`, {
  method: "POST",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X POST "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/widget/settings" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -F "heading=<heading>" \
  -F "sub_heading=<sub_heading>" \
  -F "greet_message=<greet_message>" \
  -F "color=<color>" \
  -F "show_sources=<show_sources>" \
  -F "widget_icon=<widget_icon>" \
  -F "widget_avatar=<widget_avatar>" \
  -F "widget_icon_url=<widget_icon_url>" \
  -F "widget_avatar_url=<widget_avatar_url>"

Response shape (200)

JSON

{
  "message": "<message>",
  "widget_settings": {}
}

Remove Widget Settings

DELETE/v1/agents/{agent_id}/widget/settings

Delete the agent's widget settings

Soft delete: the row is kept with deleted_at/deleted_by so the change stays auditable, and the agent falls back to the default appearance.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`	Agent ID

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.delete(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/widget/settings",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/widget/settings`, {
  method: "DELETE",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X DELETE "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/widget/settings" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"