Aliases

Aliases are optional, user-defined identifiers that provide a human-readable way to reference ChatBotKit resources. Instead of using system-generated IDs like clxyz123abc, you can assign memorable aliases like my-production-bot or customer-support-dataset to your resources.

Supported Resources

Aliases are available for the following resource types:

  • Bots - AI chatbot configurations
  • Datasets - Collections of training data and knowledge
  • Skillsets - Sets of abilities and functions
  • Files - Uploaded documents and media
  • Secrets - Secure credential storage
  • Spaces - Organizational workspaces
  • Blueprints - Reusable resource templates
  • Portals - External access points

Alias Format

Aliases must follow these rules:

  • Lowercase only - Use lowercase letters (a-z)
  • Alphanumeric - Letters and numbers (0-9)
  • Hyphens and underscores - Use - or _ as separators
  • Maximum length - Up to 128 characters
  • Unique per user - Each alias must be unique within your account for that resource type

Valid examples: my-bot, production_dataset, customer-support-v2, main-skillset

Invalid examples: My-Bot (uppercase), my bot (spaces), my@bot (special characters)

Alias Reference Forms

In alias-aware API routes, aliases can usually be provided in several forms:

  • Own resource alias - Prefix the alias with @, such as @my-production-bot
  • Parent resource alias - Prefix the alias with @@, such as @@shared-dataset
  • Sibling resource alias - Use @user-alias@resource-alias to resolve a resource owned by another user in the same account hierarchy, such as @operations@handoff-bot

These forms apply anywhere alias-aware lookup is supported.

Using Aliases for Lookup

The most common alias lookup uses the @ prefix:

GET /api/v1/bot/@my-production-bot/fetch

http

This is equivalent to looking up by ID:

GET /api/v1/bot/clxyz123abc/fetch

http

Additional Reference Forms

Use @@alias to reference a resource associated with the parent account context:

GET /api/v1/dataset/@@shared-knowledge/fetch

http

Use a compound alias when you need to resolve a sibling user's alias first and then look up the resource alias inside that user's scope:

GET /api/v1/bot/@operations@handoff-bot/fetch

http

This first resolves the sibling user alias operations, then resolves the bot alias handoff-bot within that user's resources.

User Lookup Differences

User records support @alias and @@alias, but with one important difference: @alias resolves a sub-account of the current user, and @@alias resolves a sibling user through the parent account. The sibling-style @user@resource form does not apply to user records.

Setting an Alias

Aliases can be set when creating or updating a resource by including the alias field:

POST /api/v1/bot/create
Content-Type: application/json

{
  "name": "My Production Bot",
  "alias": "my-production-bot",
  "backstory": "You are a helpful assistant..."
}

http

To update an existing resource's alias:

POST /api/v1/bot/{botId}/update
Content-Type: application/json

{
  "alias": "new-alias-name"
}

http

Note: To remove an alias, set it to an empty string or null.

Best Practices

  • Use descriptive, meaningful names that indicate the resource's purpose
  • Include environment indicators for different deployments (e.g., prod-bot, staging-bot)
  • Keep aliases short but recognizable
  • Establish naming conventions within your organization for consistency
Go to cbk.ai