Skip to main content
A Chatbot is an AI assistant scoped to your organization. You create it, configure its branding and behavior, attach the knowledge it can draw on, and ship it. The public surface lives at https://chatbot.awardee.dev/{public_slug} — anyone with the URL can converse with it (unless you password-gate it).
Chatbots are reachable three ways: directly via their public_slug, or as the destination of a scanned QR code, Product, or Object. Either way, the same chatbot handles the conversation.

​
Lifecycle

1

Create

POST /chatbots with at minimum a name. The chatbot is created in status: "draft" with a generated slug and public_slug. Pass article_ids, category_ids, system_prompt, branding, etc. inline if you have them.
2

Configure

PATCH /chatbots/{id} to set the system_prompt, welcome_message, tone, model, primary_color, logo_url, suggestion chips, and the knowledge sources (article_ids, category_ids) the agent can draw on. Optionally attach page_ids for destinations the agent can present. All ID arrays are replace-only — pass the full desired list every time.
3

Activate

PATCH /chatbots/{id} with status: "active". The public URL starts serving conversations. Flip to paused to take it offline temporarily, archived to retire it.
4

Respond

Subscribe to the conversation.* webhook events (see Conversations) to react to new sessions, hand off to humans, or sync transcripts.

​
Common workflows

​
Create, configure, publish

# 1. Create
curl -X POST https://api.awardee.dev/v1/chatbots \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "system_prompt": "You are a helpful support agent for Acme Inc.",
    "welcome_message": "Hi! How can I help?",
    "tone": "friendly",
    "primary_color": "#007495"
  }'

# 2. Activate
curl -X PATCH https://api.awardee.dev/v1/chatbots/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

​
Attach knowledge sources

Knowledge sources are how the chatbot answers from your own content. Two grains are linkable, and both are sent on the same PATCH:
  • article_ids — individual articles from your knowledge base. Pick this when you want fine-grained control.
  • category_ids — folder-level links. Attaching a category implicitly includes every article inside it, now and in the future. Pick this when you want a whole topic always available to the chatbot.
Both arrays are replace-only: PATCH with the full desired set every time. 
curl -X PATCH https://api.awardee.dev/v1/chatbots/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "article_ids": [
      "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    ],
    "category_ids": [
      "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"
    ]
  }'
article_ids and category_ids are replace-only. To detach an item, PATCH with the new list omitting it. To detach all, pass []. Omit the field entirely to leave it untouched.

​
Attach pages (destinations)

Pages are a different surface from knowledge sources. They’re destinations the agent can present to the visitor through its present_page tool — e.g. “here’s the order tracking page” or “fill out this form to start a return”. They don’t feed retrieval. Update the set with page_ids; the array fully replaces what was there.
cURL
curl -X PATCH https://api.awardee.dev/v1/chatbots/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "page_ids": [
      "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
    ]
  }'

​
Password-gate a chatbot

Send a plaintext password field on create or update. We hash it server-side and never return it. The boolean password_protected on the response tells you whether a gate is in place. 
# Set or change the password
curl -X PATCH https://api.awardee.dev/v1/chatbots/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{"password": "correct horse battery staple"}'

# Remove the gate
curl -X PATCH https://api.awardee.dev/v1/chatbots/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{"password": null}'
The hashed password is never returned. Inspect password_protected: true|false on the response to know whether a gate is set. There is no endpoint to read the password back.

​
Provide a logo by URL

logo_url accepts any public image URL. We fetch the bytes (SSRF-checked), store them in your organization’s asset library, link the resulting asset to this chatbot, and return the resolved public URL. The asset library content-addresses uploads, so re-using the same image across multiple chatbots in your organization is free — the bytes are stored once and the URL you see returned will be identical. Pass null to clear the logo. Customer CDN URLs can rot without breaking the chatbot.
cURL
curl -X PATCH https://api.awardee.dev/v1/chatbots/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{"logo_url": "https://cdn.example.com/acme-logo.png"}'
If the URL can’t be safely fetched (invalid, non-image, oversized, unsafe host) the request fails with 422 unprocessable_entity.

​
Status

StatusPublic URL serves?Meaning
draftNoDefault on create. Build it out before exposing.
activeYesLive to visitors.
pausedNoTemporarily offline. Settings preserved, returns later.
archivedNoRetired. Survives for historical conversation lookups.
Transition with PATCH /chatbots/{id} and status in the body.

​
Webhook events

Three events fire on the chatbot lifecycle. Payloads come through the standard envelope — see Webhooks overview.
​
chatbot.created
event
Fired after a chatbot row is inserted.
​
chatbot.updated
event
Fired after any field changes, including status transitions and join-set swaps (page_ids, article_ids, category_ids).
​
chatbot.deleted
event
Fired after DELETE /chatbots/{id} removes the row. Payload is minimal (id + slug + timestamp) because the source row is gone.
Sample chatbot.created / chatbot.updated payload (data field): 
{
  "chatbotId":   "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "orgId":       "c1f5b2a7-9e8d-4f6a-b3c4-d5e6f7a8b9c0",
  "name":        "Support Bot",
  "slug":        "support-bot",
  "publicSlug":  "k7Hq3M2",
  "status":      "active",
  "pageIds":     [],
  "articleIds":  ["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
  "categoryIds": ["c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"],
  "createdAt":   "2026-05-23T10:00:00Z",
  "updatedAt":   "2026-05-23T10:05:00Z"
}
Sample chatbot.deleted payload: 
{
  "chatbotId":  "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "orgId":      "c1f5b2a7-9e8d-4f6a-b3c4-d5e6f7a8b9c0",
  "slug":       "support-bot",
  "deletedAt":  "2026-05-23T11:00:00Z"
}
Conversations have their own event family (conversation.created, conversation.message_received, …) emitted by the conversations domain. See Conversations overview to react to actual chats.

​
Next

Chatbot object

Every field on the resource, with types and examples.

QR Codes

Point a scannable QR at a chatbot as its destination.