Resource 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)

Using Aliases for Lookup

Resources can be referenced by alias using the @ prefix in API calls. This works anywhere a resource identifier is accepted:

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

http

This is equivalent to looking up by ID:

GET /api/v1/bot/clxyz123abc/fetch

http

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