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:

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:

For example, deleting a space with ID space_abc123:

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

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:

For example, fetching a space with ID space_abc123:

The response includes all space details:

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:

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:

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):

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

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

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

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:

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

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

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.