Blueprints

Blueprints serve as powerful organizational tools for managing complex conversational AI setups. They allow you to group multiple related resources together, making it easier to organize, clone, and share complete AI configurations across your organization or with other users.

A blueprint acts as a container that can hold various resources including bots, datasets, skillsets, abilities, secrets, files, portals, and integrations. This makes blueprints ideal for creating reusable templates, managing multi-component AI solutions, and maintaining consistent configurations across different deployments.

Creating Blueprints

Creating a blueprint is the first step in organizing your AI resources into a manageable, reusable structure. A blueprint requires basic information including a name and description, and you can control its visibility to determine who can access it.

To create a blueprint, provide the essential metadata and specify the visibility level. The visibility setting determines whether the blueprint is private to your account, shared with your organization, or publicly accessible:

The visibility parameter accepts two values:

• private: Only accessible by the creator
• protected: Accessible by organization members

Note: The public visibility option is currently reserved for future use and not available.

Once created, you can add resources to the blueprint by specifying the blueprint ID when creating bots, datasets, and other resources. This creates a logical grouping that makes it easier to manage related components as a cohesive unit.

Important: After creation, you'll receive a blueprint ID that you should use when creating associated resources. This ensures all components are properly linked within the blueprint structure.

Listing Blueprints

You can retrieve a list of all blueprints associated with your account using the list endpoint. This is useful for displaying available templates, browsing existing configurations, and managing your blueprint collection.

The list operation supports pagination to efficiently handle large numbers of blueprints. You can control the number of items returned and navigate through results using cursor-based pagination:

The response includes an array of blueprint items, each containing the blueprint's metadata and configuration details. This allows you to display blueprint information in your application or select a blueprint for further operations.

Pagination Parameters

• cursor: Continue pagination from a specific point (obtained from previous responses)
• order: Sort order for results - asc for ascending or desc for descending (default: desc)
• take: Number of items to retrieve per request (helps manage response size)

The returned items include essential information such as the blueprint ID, name, description, visibility setting, and timestamps. You can use this data to present blueprint options to users or programmatically select blueprints based on specific criteria.

Note: The list endpoint only returns blueprints owned by the authenticated user. To access shared or public blueprints, you'll need to use the fetch endpoint with a specific blueprint ID.

Fetching a Blueprint

Retrieving a specific blueprint by its ID provides access to the blueprint's complete configuration and metadata. This is essential when you need to inspect blueprint details, verify configurations, or prepare for cloning or modification operations.

To fetch a blueprint, make a GET request with the blueprint ID in the URL path. The response includes all blueprint properties including name, description, visibility settings, metadata, and timestamps:

The blueprint ID can be either the unique identifier (a string of characters like bp_abc123) or a slug-based identifier if one was configured. This flexibility makes it easier to reference blueprints in user-friendly ways.

The fetched blueprint data includes:

• id: The unique blueprint identifier
• name: The blueprint's display name
• description: Detailed description of the blueprint's purpose
• visibility: Access control setting (private, protected, or public)
• meta: Additional metadata and custom properties
• createdAt: Timestamp when the blueprint was created
• updatedAt: Timestamp of the last modification

Authorization: You must be the owner of the blueprint to fetch it. Attempting to access a blueprint you don't own will result in an authorization error, even if you know the blueprint ID.

Updating a Blueprint

Modifying blueprint properties allows you to refine configurations, change visibility settings, and update metadata as your requirements evolve. Updates are applied to the blueprint container itself and don't affect the resources contained within it.

To update a blueprint, send a POST request with the blueprint ID and the properties you want to change. You can update the name, description, visibility setting, or metadata without affecting any of the resources associated with the blueprint:

When updating, you only need to include the fields you want to change - any omitted fields will retain their current values. This partial update approach makes it convenient to modify specific aspects of a blueprint without having to resend all its properties.

Common Update Scenarios

Changing Visibility: Update the visibility setting when you want to share a blueprint with your organization or make it publicly accessible. This is useful when promoting internal templates to wider use.

Updating Metadata: The meta field allows you to store custom properties such as UI positioning, category tags, or application-specific configuration. You can update this field to maintain additional context about your blueprint.

Renaming and Documentation: Keep blueprint names and descriptions current as the contained resources evolve, making it easier for team members to understand the purpose and contents of each blueprint.

Note: Updating a blueprint does not modify any of the resources it contains. To update contained resources like bots or datasets, you need to update them individually using their respective endpoints.

Deleting a Blueprint

Removing a blueprint permanently deletes the blueprint container and its organizational structure. This operation is useful when cleaning up unused templates or retiring deprecated configurations.

To delete a blueprint, send a POST request with the blueprint ID and an empty request body. The blueprint will be permanently removed from your account:

Critical Information About Resource Deletion:

Currently, deleting a blueprint only removes the blueprint container itself - it does NOT automatically delete the resources associated with it (bots, datasets, skillsets, integrations, etc.). These resources will become unassociated from the blueprint but will remain in your account as standalone items.

This behavior ensures that you don't accidentally lose important resources when removing a blueprint. However, it means you may need to manually clean up associated resources if you want to completely remove a blueprint and all its contents.

Best Practices Before Deletion

1. Review Associated Resources: Use the resource list endpoint to see all resources linked to the blueprint before deletion
2. Manual Cleanup: Delete individual resources manually if you want a complete removal
3. Consider Archiving: Instead of deleting, consider changing the blueprint's visibility to private and updating its name to indicate it's archived
4. Backup Important Configurations: If the blueprint contains valuable configurations, consider cloning it first as a backup

Warning: Blueprint deletion is permanent and cannot be undone. Once deleted, you cannot recover the blueprint's organizational structure, though the individual resources will remain accessible in your account.

Cloning a Blueprint

Blueprint cloning is one of the most powerful features for creating reusable AI configurations. When you clone a blueprint, you create a complete, independent copy of the entire blueprint structure including all associated resources, making it easy to replicate complex setups or share templates across different environments.

The cloning operation creates deep copies of the blueprint and all its contained resources, including bots, datasets, skillsets, abilities, secrets, files, portals, and integrations. All relationships between resources are preserved in the cloned version, and resource identifiers are automatically updated to maintain referential integrity.

To clone a blueprint, send a POST request with the blueprint ID you want to clone:

The response includes the ID of the newly created blueprint and a comprehensive map of all cloned resources, showing the relationship between original and cloned resource IDs. This mapping is useful for tracking which resources were created and for any post-clone processing you need to perform.

What Gets Cloned

The cloning operation creates copies of the following resources:

• Bots: All bot configurations including backstory, model settings, and parameters
• Datasets: Complete datasets with structure and configuration (records are not cloned)
• Skillsets: All skillset definitions and configurations
• Abilities: Custom abilities and their configurations
• Secrets: Secret placeholders (values are intentionally not copied for security)
• Files: File references and metadata
• Portals: Portal configurations with new unique slugs to avoid conflicts
• Integrations: All integration types including widget, Slack, Discord, Telegram, WhatsApp, Messenger, Twilio, email, trigger, sitemap, Notion, extract, support, and MCP server integrations

Resource Reference Handling

One of the most sophisticated aspects of blueprint cloning is how it handles resource references. When resources reference each other (for example, a bot referencing a dataset), the cloning process automatically updates these references to point to the newly created resources. This ensures the cloned blueprint maintains the same functional relationships as the original.

For example, if the original blueprint has a bot that uses a specific dataset, the cloned bot will automatically reference the cloned version of that dataset rather than the original one.

Security and Data Handling

Secret Values: For security reasons, secret values are deliberately not copied during cloning. The cloned resources will have secret placeholders, but you'll need to configure actual secret values manually after cloning.

Authentication Tokens: Integrations that use authentication tokens (like Trigger integrations, WhatsApp, Messenger, and MCP server integrations) receive new automatically generated tokens to ensure security and prevent conflicts.

Portal Slugs: Portal slugs are automatically modified to include a random suffix, preventing conflicts with existing portals while maintaining a similar naming pattern.

Cloning Public Blueprints

You can clone public blueprints from the hub or from other users, allowing you to use community-created templates as starting points for your own configurations. When cloning a public blueprint, all resources are copied to your account, and you become the owner of the cloned version with full control over modifications.

Post-Clone Tasks

After cloning a blueprint, you typically need to:

1. Configure Secrets: Add actual secret values for any integrations or abilities that require them
2. Update Authentication: Configure API keys and tokens for external integrations
3. Customize Resources: Modify cloned resources to fit your specific use case
4. Test Functionality: Verify that all components work correctly in their new context
5. Update Portal Slugs: Adjust portal slugs to match your preferred naming convention if needed

Performance Note: Cloning large blueprints with many resources may take several seconds to complete as each resource is individually created and linked. The operation is performed atomically to ensure consistency.