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.

POST /api/v1/space/{spaceId}/site/create
Content-Type: application/json

{
  "domain": "myapp.chatbotkit.space",
  "name": "My App Site",
  "description": "Production site for my application",
  "prefix": "/app",
  "index": "index.html",
  "notFound": "404.html",
  "alias": "main-site"
}

http

Response:

{
  "id": "site_abc123def456"
}

json

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.

GET /api/v1/space/{spaceId}/site/{siteId}/fetch

http

Response:

{
  "id": "site_abc123def456",
  "spaceId": "space_xyz789",
  "alias": "main-site",
  "name": "My App Site",
  "description": "Production site for my application",
  "domain": "myapp.chatbotkit.space",
  "prefix": "/app",
  "index": "index.html",
  "notFound": "404.html",
  "createdAt": "2025-06-24T10:30:00Z",
  "updatedAt": "2025-06-24T10:30:00Z"
}

json

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.

GET /api/v1/space/{spaceId}/site/list?order=desc&take=20

http

Response:

{
  "items": [
    {
      "id": "site_abc123def456",
      "alias": "main-site",
      "name": "My App Site",
      "description": "Production site for my application",
      "domain": "myapp.chatbotkit.space",
      "prefix": "/app",
      "index": "index.html",
      "notFound": "404.html",
      "createdAt": "2025-06-24T10:30:00Z",
      "updatedAt": "2025-06-24T10:30:00Z"
    }
  ],
  "cursor": "eyJpZCI6InNpdGVfYWJjMTIzIn0="
}

json

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.

POST /api/v1/space/{spaceId}/site/{siteId}/update
Content-Type: application/json

{
  "domain": "newdomain.chatbotkit.space",
  "prefix": "/v2",
  "index": "home.html",
  "notFound": "error.html"
}

http

Response:

{
  "id": "site_abc123def456"
}

json

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.

POST /api/v1/space/{spaceId}/site/{siteId}/delete
Content-Type: application/json

{}

http

Response:

{
  "id": "site_abc123def456"
}

json

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
Go to cbk.ai