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.
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",
  "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
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
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:

Export or backup any important configuration
Add a temporary redirect or maintenance page
Notify users of the change
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