Spaces

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.

When creating a space, you can optionally associate it with a contact, which helps establish relationships between spaces and specific users or organizations. This association enables better organization and filtering of spaces based on contact relationships.

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",
  "contactId": "contact_abc123",
  "meta": {
    "department": "support",
    "priority": "high"
  }
}

http

The API returns the unique identifier for the newly created space, which can then be used to manage conversations, add team members, and configure space-specific settings.

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.

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.

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.

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.

Go to cbk.ai