Space Sites

Space Sites allow you to configure custom domain hosting and content delivery through your ChatBotKit spaces. A space site represents a hosted location where your content is served at a specific domain with optional path prefixes and custom error pages.

Creating a Site

To create a new site within a space, you'll specify the domain where your content will be served, along with optional configuration for path prefixes, directory indexes, and not-found pages. The domain must follow ChatBotKit's domain naming conventions and should be globally unique within the platform.

Response:

Parameters:

• domain (required): The domain where your site will be served (e.g., myapp.chatbotkit.space). Must be a valid domain following ChatBotKit conventions.
• name: Human-readable name for the site
• description: Detailed description of the site's purpose
• prefix: Optional path prefix within the space to serve from (e.g., /app). Useful when hosting multiple sites from one space.
• index: Default directory index file (default: index.html). Used when users access the site without a specific file.
• notFound: Filename to serve for not-found errors (default: 404.html). Returns HTTP 404 when accessed.
• alias: Optional reference identifier for your site
• meta: Optional key-value metadata object

Important Notes:

• Domains must be unique within your ChatBotKit workspace
• The domain configuration determines where visitors access your content
• Path prefixes are useful for organizing multiple sites within a single space
• Both index and notFound files must exist in your space content

Fetching a Single Site

Retrieve detailed information about a specific site by its ID. This endpoint returns complete site configuration including domain, prefixes, and serving options.

Response:

URL Parameters:

• spaceId: The ID or identifier of the space containing the site
• siteId: The ID or alias of the site to retrieve

Response Properties:

• id: Unique identifier for the site
• spaceId: The space this site belongs to
• domain: The domain where this site is served
• prefix: Path prefix within the space (if configured)
• index: Directory index filename
• notFound: Error page filename
• name and description: Metadata for organization
• createdAt/updatedAt: Timestamps for tracking changes

Error Cases:

• Returns 404 if the space or site doesn't exist
• Returns 401 if you don't have permission to access the space

Listing Sites

Retrieve a paginated list of all sites in your space. This endpoint supports cursor-based pagination to efficiently load large site collections and filtering by metadata or domain.

Response:

Query Parameters:

• cursor: Pagination cursor from the previous response to fetch the next page
• order: Sort order for results (asc or desc, default: desc)
• take: Number of items to retrieve per page (typically 10-100)
• meta: Filter sites by metadata key-value pairs (supports ?meta[key]=value syntax)

Response Format:

• items: Array of site objects with all configuration details
• cursor: Pagination token for fetching the next page of results

Pagination Notes:

• Always check if the returned cursor is present before making the next request
• When cursor is empty or missing, you've reached the end of the list
• Use the take parameter to control page size based on your needs
• Results are returned in reverse chronological order by default

Updating a Site

Modify the configuration of an existing site. You can update any combination of site properties including domain, serving prefixes, index files, and metadata.

Response:

Updateable Fields:

• domain: Change where the site is served (must remain unique)
• prefix: Modify the path prefix within the space
• index: Update the directory index filename
• notFound: Change the not-found error page
• name: Update the site display name
• description: Change the site description
• alias: Update the reference identifier
• meta: Update or add metadata

Important Considerations:

• Changing the domain will affect how visitors access your site
• If you change the domain, existing bookmarks and links will break
• The new domain must be available and unique within your workspace
• Index and notFound files must exist in your space after updating
• Partial updates are supported - only include fields you want to change
• All string fields can be set to null or empty string to clear them (except domain)

Best Practices:

• Plan domain changes during low-traffic periods
• Test configuration changes on a staging site before production
• Keep descriptive names and descriptions for easier management
• Use custom metadata for organizing related sites

Deleting a Site

Permanently remove a site from your space. Deletion is irreversible and will immediately stop serving content at the site's domain. Any active connections to the site will be terminated.

Response:

URL Parameters:

• spaceId: The space containing the site
• siteId: The ID of the site to delete

Important Warnings:

⚠️ This action is permanent and cannot be undone.

• Deleting a site immediately stops serving content at its domain
• All active connections to the domain will be closed
• DNS records pointing to the domain should be updated separately
• Any bookmarks or links to the deleted site will return 404 errors
• Consider creating a redirect or announcement before deletion

Best Practices Before Deletion:

1. Export or backup any important configuration
2. Update DNS records to remove the domain
3. Add a temporary redirect or maintenance page
4. Notify users of the change
5. Wait for DNS propagation before deletion
6. Monitor for broken links after deletion

Recovery Options:

• If accidentally deleted, you can immediately recreate the site with the same domain
• Configuration cannot be recovered if you didn't maintain backups
• Contact support if you need assistance with recovery