Spaces

Listing Spaces

Retrieving a list of your spaces is essential for discovering and managing your workspace environments. The list endpoint provides comprehensive filtering and pagination capabilities, allowing you to efficiently navigate through large collections of spaces.

The list operation supports cursor-based pagination for optimal performance when working with extensive space collections. You can control the number of results per page, the sort order, and apply filters based on metadata or specific field values such as associated contact identifiers.

To retrieve your spaces, send a GET request to the list endpoint:

GET /api/v1/space/list?order=desc&take=20

http

For pagination through large result sets, use the cursor parameter returned from previous requests:

GET /api/v1/space/list?cursor=eyJpZCI6InNwYWNlXzEyMyJ9&order=desc&take=20

http

You can also filter spaces by specific criteria. For example, to find all spaces associated with a particular contact:

GET /api/v1/space/list?contactId=contact_abc123

http

The response includes an array of space objects containing their identifiers, names, descriptions, associated contact IDs, metadata, and timestamps. This comprehensive information enables you to build rich user interfaces for space management and selection.

Performance Tip: Use the take parameter to limit result set sizes and improve response times, especially when implementing search or autocomplete features.

Spaces provide a powerful way to organize your conversational AI resources into distinct, isolated environments. Each space acts as a container for conversations, contacts, and other related resources, allowing teams to maintain separate contexts for different projects, clients, or use cases.

Creating Spaces

Creating a space is the foundational step in organizing your conversational resources into isolated workspaces. Each space can be configured with a meaningful name and description to help team members understand its purpose and scope.

To create a new space, send a POST request with the space details:

POST /api/v1/space/create
Content-Type: application/json

{
  "name": "Customer Support - ACME Corp",
  "description": "Dedicated space for ACME Corporation support operations",
  "blueprintId": "blueprint_xyz789",
  "contactId": "contact_abc123",
  "meta": {
    "department": "support",
    "priority": "high"
  }
}

http

The API returns the unique identifier for the newly created space, which you use to manage conversations, configure space-specific settings, and share the workspace with contacts.

Space Sharing and Collaboration

Spaces support sharing with contacts, enabling collaborative workflows where end users (represented as contacts) can participate in the same isolated workspace. You establish this relationship by providing a contactId when creating or updating a space.

Once a contact is associated with a space, the contact's conversations, tasks, and memories can be organized within that shared workspace context. This contact-space relationship is the foundation for multi-participant scenarios such as team collaboration, client portals, and segmented support workflows.

To create a space shared with a specific contact:

POST /api/v1/space/create
Content-Type: application/json

{
  "name": "Project Alpha Workspace",
  "description": "Shared workspace for Project Alpha team",
  "contactId": "contact_alice123",
  "meta": {
    "project": "alpha",
    "team": "engineering"
  }
}

http

You can retrieve all spaces associated with a given contact using the /api/v1/contact/{contactId}/space/list endpoint. This makes it easy to build workspace-aware routing, context-specific bots, and per-workspace analytics.

Contact-Space Association:

  • One contact can be linked to multiple spaces
  • A space holds a reference to one contact at a time via contactId
  • Update the contactId on a space to reassign it to a different contact
  • Set contactId to null via update to remove the association

Blueprint-Based Workspace Templates

The blueprintId field associates a space with a blueprint, enabling templated workspace deployments. When you clone a blueprint, all spaces linked to it are replicated as part of the deployment, preserving your workspace structure across different projects, clients, or environments.

This is particularly useful for agencies or SaaS applications that need to provision identical workspace configurations for each new customer:

POST /api/v1/space/create
Content-Type: application/json

{
  "name": "Onboarding Workspace",
  "blueprintId": "blueprint_onboarding_template",
  "meta": {
    "client": "acme-corp",
    "tier": "enterprise"
  }
}

http

Using Metadata for Organization

Custom metadata (meta) lets you attach arbitrary key-value pairs to a space for organization, filtering, and integration with external systems. Use metadata to tag spaces by department, project, environment, or any other business-specific classification:

{
  "meta": {
    "environment": "production",
    "region": "us-east",
    "tier": "enterprise",
    "owner": "team-alpha"
  }
}

json

Metadata is queryable via the list and export endpoints, enabling you to filter spaces by any combination of metadata properties.

Fetching a Space

Retrieving detailed information about a specific space is a common operation when building applications that need to display or work with space configuration and metadata. The fetch endpoint provides complete space details including all associated properties and relationships.

When fetching a space, you receive the full set of space properties including its unique identifier, name, description, any associated contact relationships, custom metadata, and timestamp information for creation and last update. This comprehensive data enables you to build detailed space management interfaces and make informed decisions about space operations.

To retrieve a specific space by its identifier:

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

http

For example, fetching a space with ID space_abc123:

GET /api/v1/space/space_abc123/fetch

http

The response includes all space details:

{
  "id": "space_abc123",
  "name": "Customer Support - ACME Corp",
  "description": "Dedicated space for ACME Corporation support operations",
  "contactId": "contact_xyz789",
  "meta": {
    "department": "support",
    "priority": "high"
  },
  "createdAt": "2025-01-01T10:00:00.000Z",
  "updatedAt": "2025-01-05T14:30:00.000Z"
}

json

Updating a Space

Modifying space properties allows you to keep workspace information current as project requirements evolve or organizational needs change. The update operation provides flexibility to modify any configurable space property while maintaining the space's identity and existing relationships.

When updating a space, you can modify its name, description, associated contact, and custom metadata. The update operation intelligently merges metadata changes, preserving existing metadata keys that aren't explicitly updated while applying new values for keys that are provided.

To update a space, send a POST request with the updated properties:

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

{
  "name": "Premium Support - ACME Corp",
  "description": "Upgraded support space with priority handling",
  "contactId": "contact_xyz789",
  "meta": {
    "tier": "premium",
    "sla": "4-hour response"
  }
}

http

All fields in the update request are optional, allowing you to modify only the properties that need changing. For example, to update just the name:

POST /api/v1/space/space_abc123/update
Content-Type: application/json

{
  "name": "Updated Space Name"
}

http

Metadata Management: When updating metadata, the system intelligently merges new metadata with existing values. To remove a metadata key, you must explicitly set it to null in your update request. This behavior ensures that partial metadata updates don't inadvertently delete existing metadata properties.

Deleting a Space

Permanently removing a space is a critical operation that should be performed with caution, as it irreversibly removes the space and may affect associated resources. The delete operation ensures proper cleanup of all space-related data while maintaining referential integrity across the system.

When you delete a space, the system performs a comprehensive cleanup process that removes the space record and handles any cascade effects on related resources. This cleanup ensures that no orphaned data remains in the system and that all references to the deleted space are properly handled.

To permanently delete a space:

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

{}

http

For example, deleting a space with ID space_abc123:

POST /api/v1/space/space_abc123/delete
Content-Type: application/json

{}

http

The API returns the ID of the deleted space as confirmation:

{
  "id": "space_abc123"
}

json

Important Considerations:

  • Irreversible Operation: Space deletion is permanent and cannot be undone. Ensure you have backed up any critical data before proceeding.

  • Related Resources: Consider the impact on conversations, contacts, or other resources that may be associated with the space. The deletion process handles these relationships according to configured cascade rules.

Best Practice: Before deleting a space, consider archiving or exporting its data if you need to maintain historical records for compliance or reference purposes. Once deleted, the space and its configuration cannot be recovered.

Exporting Spaces

Exporting spaces enables bulk data retrieval in various formats, supporting backup operations, data migration workflows, and integration with external systems. The export endpoint provides flexible output formats including JSON, JSONL (JSON Lines), and CSV, making it easy to work with space data in different contexts.

The export operation supports the same pagination and filtering capabilities as the list endpoint, but with enhanced format support for large-scale data operations. This flexibility allows you to export complete space collections or filtered subsets based on your specific requirements.

To export spaces in JSON format (default):

GET /api/v1/space/export
Accept: application/json

http

For streaming exports using JSONL format, which is ideal for processing large datasets line-by-line:

GET /api/v1/space/export
Accept: application/jsonl

http

To export as CSV for spreadsheet applications or data analysis tools:

GET /api/v1/space/export
Accept: text/csv

http

The export operation supports pagination to handle large space collections efficiently:

GET /api/v1/space/export?order=desc&take=100

http

Format Details:

  • JSON: Returns a structured object with an items array containing all space records. Best for programmatic processing and API integrations.

  • JSONL: Returns newline-delimited JSON objects, with each line containing a single space record. Ideal for streaming processing and ETL pipelines.

  • CSV: Returns comma-separated values with headers, compatible with spreadsheet applications. Metadata fields are serialized as YAML strings for readability.

Use Cases:

  • Backup and Recovery: Regular exports ensure you have offline copies of your space configurations for disaster recovery scenarios.

  • Data Migration: Export spaces when moving between environments or transitioning to different systems.

  • Analytics and Reporting: Export to CSV for analysis in spreadsheet applications or business intelligence tools.

  • System Integration: Use JSONL format for efficient integration with data processing pipelines and external systems.

Go to cbk.ai