Space Sites

A space site publishes content at <slug>.<space apex> with optional path prefixes and custom error pages.

Creating a Site

Specify the globally unique slug used beneath the configured space apex, along with optional serving configuration.

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

{
  "slug": "myapp",
  "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:

  • slug (required): The DNS-label slug used in <slug>.<space apex>
  • 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.
  • access: public (default) serves the site to anyone; private serves it only through a temporary link (see Temporary Site Links)
  • alias: Optional reference identifier for your site
  • meta: Optional key-value metadata object

Important Notes:

  • Slugs are unique across the deployment
  • Custom domains are not supported
  • 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, including its slug 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",
  "slug": "myapp",
  "prefix": "/app",
  "index": "index.html",
  "notFound": "404.html",
  "access": "public",
  "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
  • slug: The subdomain slug beneath the configured space apex
  • prefix: Path prefix within the space (if configured)
  • index: Directory index filename
  • notFound: Error page filename
  • access: public or private
  • 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 and filtering by metadata or slug.

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",
      "slug": "myapp",
      "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 slug, serving files, and metadata of an existing site.

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

{
  "slug": "new-site",
  "prefix": "/v2",
  "index": "home.html",
  "notFound": "error.html"
}

http

Response:

{
  "id": "site_abc123def456"
}

json

Updateable Fields:

  • slug: Change the subdomain slug (must remain unique)
  • prefix: Modify the path prefix within the space
  • index: Update the directory index filename
  • notFound: Change the not-found error page
  • access: Switch between public and private
  • 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 slug changes the site URL, so existing links will break
  • The new slug must be available across the deployment
  • 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 slug)

Best Practices:

  • Plan slug 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 immediately stops serving content at the site's apex subdomain.

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 apex subdomain
  • 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. Add a temporary redirect or maintenance page
  3. Notify users of the change
  4. Monitor for broken links after deletion

Recovery Options:

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

A site with access set to private is not open to the public: without a valid link it answers 404, exactly like a site that does not exist. Mint a temporary link to open it, optionally limited to one folder so that each sub-site can be shared on its own:

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

{ "path": "reports/q1", "durationInSeconds": 3600 }

http

Response:

{
  "url": "https://myapp.example.space/reports/q1?cbk_site_token=...",
  "expiresAt": "2025-06-24T11:30:00.000Z"
}

json

Parameters:

  • path: The folder the link unlocks, relative to the site root. Leave it empty to unlock the whole site.
  • durationInSeconds: How long the link works, from 60 seconds to 7 days (default: 1 hour).

How it works:

  • Opening the link sets a short-lived cookie for that site and folder, then redirects to the same address without the token, so pages and their relative assets load normally and the token stays out of browser history.
  • The link and the cookie stop working when the link expires, when the site slug changes, or for pages outside the unlocked folder.
  • Private pages are sent with Cache-Control: private, no-store and are not indexed by search engines.
  • Links also work for public sites, so a site can be made private later without breaking links that are already shared.
Go to cbk.ai