Skip to main content
A Chatbot represents an AI assistant scoped to your organization. This page is the field-by-field reference for the wire format you’ll see on every chatbots endpoint.

​
Identifiers

​
object
string
required
Always "chatbot". Sentinel that identifies the resource type on responses.
​
id
string
required
Bare UUID. Stable for the lifetime of the chatbot.
​
slug
string
required
Internal slug used in dashboard URLs. Auto-generated from name. Not part of the public scan URL.
​
public_slug
string
required
Short opaque slug used to build the public chatbot URL: https://chatbot.awardee.dev/{public_slug}. Immutable.
​
url
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.
​
status
string
required
One of "draft", "active", "paused", "archived". Only active chatbots serve their public URL.

​
Display

​
name
string
required
Human-readable name. Shown in the dashboard and as the assistant header on the public page.
​
description
string | null
Internal description. Surface-area for your own notes. Not shown to end users.
​
welcome_message
string | null
First message the assistant displays before the visitor types anything.
​
welcome_subtitle
string | null
Secondary text under the welcome message.
​
primary_color
string | null
Hex color (#RRGGBB). Drives the accent on the public surface.
​
logo_url
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.
​
suggestions
string[] | null
Optional list of suggested first-message chips shown to the visitor.

​
Behavior

​
system_prompt
string | null
System prompt prepended to every conversation. Defines the assistant’s role, constraints, and voice.
​
model
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.
​
tone
string | null
One of "professional", "friendly", "casual", "formal", "empathetic". Layered on top of system_prompt for tone shaping.
​
human_support_enabled
boolean
required
When true, the chatbot can hand off to a human via the conversations inbox.
​
password_protected
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.
​
web_search_enabled
boolean
required
When true, the assistant has a web-search tool available.
​
location
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.
​
article_ids
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.
​
category_ids
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

​
page_ids
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.
page_ids, article_ids, and category_ids are all replace-only. PATCH with the full list every time. Omit a field to leave it untouched; pass [] to detach everything in that group. Every referenced page, article, and category id must belong to your organization, or the request is rejected with 422 unprocessable.

​
Stats

​
conversation_count
number | null
Total conversations for this chatbot. Computed at read time; null if the count couldn’t be loaded.
​
last_active_at
string | null
RFC 3339 timestamp of the most recent inbound message. null if no conversations yet.

​
Timestamps

​
created_at
string
required
RFC 3339 creation timestamp.
​
updated_at
string
required
RFC 3339 timestamp of the last update to this row (status, settings, page attachments).

​
Example

{
  "object": "chatbot",
  "id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Support Bot",
  "slug": "support-bot",
  "public_slug": "k7Hq3M2",
  "url": "https://chatbot.awardee.dev/k7Hq3M2",
  "status": "active",
  "description": "Tier-1 support for the storefront.",
  "welcome_message": "Hi! How can I help?",
  "welcome_subtitle": "Average reply in under a minute.",
  "system_prompt": "You are a helpful support agent for Acme Inc.",
  "model": "claude-sonnet-4-5",
  "primary_color": "#007495",
  "logo_url": "https://cdn.example.com/logo.png",
  "tone": "friendly",
  "suggestions": [
    "Where's my order?",
    "Start a return"
  ],
  "human_support_enabled": true,
  "password_protected": false,
  "page_ids": [
    "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  ],
  "article_ids": [
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "category_ids": [
    "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"
  ],
  "location": {
    "enabled": false,
    "address": null,
    "lat": null,
    "lng": null,
    "place_id": null
  },
  "web_search_enabled": false,
  "conversation_count": 1247,
  "last_active_at": "2026-05-23T09:58:21Z",
  "created_at": "2026-05-01T08:00:00Z",
  "updated_at": "2026-05-23T09:58:21Z"
}