chatbots endpoint.
Identifiers
string
required
Always
"chatbot". Sentinel that identifies the resource type on responses.string
required
Bare UUID. Stable for the lifetime of the chatbot.
string
required
Internal slug used in dashboard URLs. Auto-generated from
name. Not part of
the public scan URL.string
required
Short opaque slug used to build the public chatbot URL:
https://chatbot.awardee.com/{public_slug}. Immutable.string
required
Canonical public-facing URL a visitor uses to reach the chatbot. Derived from
public_slug — provided as a convenience so you don’t have to assemble it
client-side.string
required
One of
"draft", "active", "paused", "archived". Only active chatbots
serve their public URL.Display
string
required
Human-readable name. Shown in the dashboard and as the assistant header on the
public page.
string | null
Internal description. Surface-area for your own notes. Not shown to end users.
string | null
First message the assistant displays before the visitor types anything.
string | null
Secondary text under the welcome message.
string | null
Hex color (
#RRGGBB). Drives the accent on the public surface.string | null
Public URL to the chatbot’s logo. Accepts any public image URL on write — we
fetch the bytes (SSRF-checked), store them in your organization’s asset
library, link the asset to this chatbot, and return the resolved public URL.
Customer CDN URLs can rot without breaking the chatbot. Uploads of identical
bytes (across chatbots within the same organization) are de-duplicated — you
may see the same URL returned for two chatbots if you upload the same logo to
both.
object[] | null
Optional list of starter prompts shown to the visitor beneath the welcome
heading. Each item has an optional
title and a required prompt.Behavior
string | null
System prompt prepended to every conversation. Defines the assistant’s role,
constraints, and voice.
string | null
Model identifier. When
null, the org-default model is used. See
Models for the list of supported IDs and their credit cost
per message.string | null
One of
"professional", "friendly", "casual", "formal", "empathetic".
Layered on top of system_prompt for tone shaping.boolean
required
When
true, the chatbot can hand off to a human via the conversations inbox.boolean
required
true if a password gate is set. Set or clear via the write-only password
field on POST / PATCH. The hash itself is never returned.boolean
required
When
true, the assistant has a web-search tool available.object
required
Optional location context the assistant can use (e.g. for “near me” answers).
Knowledge sources
Two grains of knowledge link to a chatbot. The agent reads from both at retrieval time — a category implicitly includes every article inside it, current and future.string[]
required
UUIDs of Articles the chatbot can draw on as knowledge.
Write the desired set with
article_ids on POST or PATCH and the join is
fully replaced.string[]
required
UUIDs of Article Categories attached as
folder-level knowledge sources. Every article inside the category (now and in
future) is available to the agent. Write the desired set with
category_ids
on POST or PATCH and the join is fully replaced.Destinations
string[]
required
UUIDs of Pages the agent can present to the visitor via its
present_page tool, in display order. These are destinations the agent can
route to mid-conversation, not knowledge it reads from. Write the desired set
with page_ids on POST or PATCH and the join is fully replaced.Stats
number | null
Total conversations for this chatbot. Computed at read time;
null if the
count couldn’t be loaded.string | null
RFC 3339 timestamp of the most recent inbound message.
null if no
conversations yet.Timestamps
string
required
RFC 3339 creation timestamp.
string
required
RFC 3339 timestamp of the last update to this row (status, settings, page
attachments).