Bots

A Bot is the channel-agnostic configuration hub for your AI assistant. Every gateway request authenticated with a credential that has a bot bound to it gets the bot’s system prompt, skill instructions, and plugin allowlist applied automatically — without any changes to the request body. Source: CRA-219, CRA-225

Read Concepts first if you haven’t already.

What a Bot is

A Bot is a tuple of:

Field	Purpose
model	The organisation model used when no model is sent in the request.
credential	Optional gateway credential the bot is pre-bound to.
systemPrompt	Prepended to every request as a system message prefix.
skills[]	Ordered list of skill slugs attached to this bot.
plugins[]	Allowlist of plugin IDs the bot may inject into requests.
toolGatingMode	all_at_once (default) or on_demand. See Skills.
tokenBudgetPct	Percent of the model’s context window reserved for overhead (1–50).
toolCountCap	Maximum number of tools the bot may expose in a single request.

A Bot is always-on. There is no flag to enable or disable bot resolution — every request whose credential has a default_bot_id is resolved through the bot stack. Source: CRA-225 (BOTS_ENABLED flag removed pre-prod)

Creating a Bot

Two paths:

Install an Industry Pack. Open Marketplace in the control panel and install a pack (Realtor, Medical Clinic, or General SMB). The install wizard creates a fully configured Bot — with integrations, skills, and a system prompt — in one transaction. See Marketplace.

Compose manually. Open Bots → New Bot in the control panel. Set the model, write the system prompt, pick skills from your skill library, choose plugins from your installed integrations, and configure the token-budget controls.

Binding a Bot to a credential

A Bot is only active when it is attached to a gateway credential. Source: CRA-229

1. Open Credentials in the control panel.
2. Select a gateway key.
3. Under Bot binding, choose the bot from the dropdown.
4. Optionally enable Allow per-request override (bot_override_allowed) so callers can switch bots via metadata.crafted.botId.

When a credential has no bot bound, requests through it run without bot resolution.

You can also set the binding via the API:

PATCH /credentials/{credentialId}/bot-config
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>
Content-Type: application/json

{
  "defaultBotId": "<bot-uuid>",
  "botOverrideAllowed": false
}

See Credentials for the full credentials reference.

Sending a request with the default bot

No request body changes are needed. The bot resolves from the credential automatically:

curl "https://api-staging.craftedai.co/v1/chat/completions" \
  -H "Authorization: Bearer $CRAFTED_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "What properties do you have in Scottsdale under $600k?" }
    ]
  }'

The gateway prepends the bot’s system prompt, injects allowed plugin tools, applies skill instructions, runs the token-budget guard, and then calls the upstream model.

Per-request bot override

When botOverrideAllowed is true on the credential, the caller can switch to any org-owned bot for a single request:

curl "https://api-staging.craftedai.co/v1/chat/completions" \
  -H "Authorization: Bearer $CRAFTED_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "crafted": { "botId": "<other-bot-uuid>" } },
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "What is my appointment status?" }
    ]
  }'

The metadata.crafted namespace is stripped before the request reaches the upstream provider. See Concepts — per-request override for the full semantics.

Testing different system prompts

bot_override_allowed is useful during development when you want to A/B test different bot configurations from a single credential without minting new gateway keys.

Token preview

Before deploying a bot, check whether its configuration fits within the token budget using the pre-flight preview endpoint:

GET /bots/{botId}/token-preview?model=gpt-4o-mini
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>

Response:

{
  "modelSlug": "gpt-4o-mini",
  "modelContextWindow": 128000,
  "budgetPct": 10,
  "budgetTokens": 12800,
  "injectedTokens": 3420,
  "breakdown": {
    "systemPrompt": 280,
    "alwaysSkillsTotal": 1940,
    "toolSchemasTotal": 1200,
    "toolCount": 8
  },
  "overBudget": false,
  "toolOverCap": false
}

overBudget: true or toolOverCap: true means the bot will return a 400 error on every request using that model. Reduce the system prompt, trim skills, or raise tokenBudgetPct / toolCountCap as appropriate.

The control panel’s Bots editor shows this breakdown inline as you configure the bot, updating in real time as you change the model or adjust the system prompt. Source: CRA-220, CRA-221

Admin note on the BOTS_ENABLED flag

An early design included a BOTS_ENABLED environment flag for gradual rollout. It was removed before shipping — Crafted AI is pre-production and all bot behaviour is always active. There is no flag to set or unset.

Next steps

• Read Skills to understand how always and on_demand mode skills shape the system prompt and tool list.
• Read Marketplace to install an Industry Pack and get a production-ready bot in minutes.
• Read Credentials for credential rotation and rate-limit configuration.
• Read Gateway API for the full request/response reference.