Space API

The Space API manages conversational spaces (assistants) and their chats in Unique AI.

Overview

Spaces are conversational assistants with configured tools, scope rules, and modules. Use this API to:

• Create spaces
• Delete spaces
• Manage space access control
• Send messages to spaces
• Manage space chats
• Retrieve space configuration
• Access message history

Methods

unique_sdk.Space.create_space - Create a new space

Create a new space (assistant) with the specified configuration.

Parameters:

• name (str, required) - The name of the space
• fallbackModule (str, required) - The fallback module name (must match one of the module names)
• modules (List[ModuleParams], required) - List of modules to create for the space
  • name (str, required) - The name of the module
  • description (str, optional) - The description of the module
  • weight (int, optional) - The weight/priority of the module
  • isExternal (bool, optional) - Whether the module is external
  • isCustomInstructionEnabled (bool, optional) - Whether custom instruction is enabled
  • configuration (Dict, optional) - Configuration for the module
  • toolDefinition (Dict, optional) - Tool definition for the module
• explanation (str, optional) - Description of the space
• alert (str, optional) - Alert message for the space
• chatUpload (Literal["ENABLED", "DISABLED"], optional) - Chat upload setting
• languageModel (str, optional) - Language model to use
• isExternal (bool, optional) - Whether the space is external
• isPinned (bool, optional) - Whether the space is pinned
• uiType (Literal["MAGIC_TABLE", "UNIQUE_CUSTOM", "TRANSLATION", "UNIQUE_AI"], optional) - UI type
• settings (Dict, optional) - Space settings

Returns:

Returns a Space object.

Example:

space = unique_sdk.Space.create_space(
    user_id=user_id,
    company_id=company_id,
    name="Customer Support Assistant",
    fallbackModule="UniqueAi",
    modules=[
        {
            "name": "UniqueAi",
            "weight": 10000
        }
    ]
)

print(f"Created space: {space['id']}")

Example - With Additional Options:

space = unique_sdk.Space.create_space(
    user_id=user_id,
    company_id=company_id,
    name="Engineering Assistant",
    fallbackModule="UniqueAi",
    modules=[
        {
            "name": "UniqueAi",
            "weight": 10000,
            "description": "Main AI module"
        }
    ],
    explanation="Assistant for engineering team",
    chatUpload="ENABLED",
    isPinned=True
)

unique_sdk.Space.get_space_access - Get space access entries

Get access entries for a space. Requires manage access to the space.

Parameters:

• space_id (str, required) - The ID of the space

Returns:

Returns a SpaceAccessResponse object.

Example:

access = unique_sdk.Space.get_space_access(
    user_id=user_id,
    company_id=company_id,
    space_id="assistant_hjcdga64bkcjnhu4"
)

for entry in access["access"]:
    print(f"{entry['entityType']}: {entry['entityId']} - {entry['type']}")

unique_sdk.Space.add_space_access - Add access to a space

Add access entries to a space. Requires manage access to the space.

Parameters:

• space_id (str, required) - The ID of the space
• accessIds (List[AccessEntry], required) - List of access entries to add
  • entityId (str, required) - The ID of the entity (user or group)
  • entityType (Literal["USER", "GROUP"], required) - The type of entity
  • type (Literal["USE", "MANAGE", "UPLOAD"], required) - The type of access

Returns:

Returns an AddSpaceAccessResponse object.

Example:

result = unique_sdk.Space.add_space_access(
    user_id=user_id,
    company_id=company_id,
    space_id="assistant_hjcdga64bkcjnhu4",
    accessIds=[
        {
            "entityId": "228959553377538182",
            "entityType": "USER",
            "type": "USE"
        }
    ]
)

Example - Add Group Access:

result = unique_sdk.Space.add_space_access(
    user_id=user_id,
    company_id=company_id,
    space_id="assistant_hjcdga64bkcjnhu4",
    accessIds=[
        {
            "entityId": "group_abc123",
            "entityType": "GROUP",
            "type": "MANAGE"
        }
    ]
)

unique_sdk.Space.delete_space_access - Remove access from a space

Remove access entries from a space. Requires manage access to the space.

Parameters:

• space_id (str, required) - The ID of the space
• accessIds (List[str], required) - List of access entry IDs to delete

Returns:

Returns a DeleteSpaceAccessResponse object.

Example:

result = unique_sdk.Space.delete_space_access(
    user_id=user_id,
    company_id=company_id,
    space_id="assistant_hjcdga64bkcjnhu4",
    accessIds=["access_yptvsdq8sqjfsxe1ih0mnug7"]
)

unique_sdk.Space.create_message - Send message in space

Send a message in a space. Creates a new chat if no chatId provided.

Parameters:

• assistantId (str, required) - Space/assistant ID
• text (str, optional) - Message text
• chatId (str, optional) - Continue existing chat or start new
• toolChoices (List[str], optional) - List of tools to use (e.g., ["WebSearch", "InternalSearch"])
• scopeRules (Dict[str, Any], optional) - UniqueQL filter for document scope

Returns:

Returns a Space.Message object.

Example - New Chat:

message = unique_sdk.Space.create_message(
    user_id=user_id,
    company_id=company_id,
    assistantId="assistant_abc123",
    text="Hello, how can you help me?",
    toolChoices=["WebSearch", "InternalSearch"]
)

chat_id = message.chatId  # Save for next message

Example - Continue Chat:

message = unique_sdk.Space.create_message(
    user_id=user_id,
    company_id=company_id,
    chatId="chat_dejfhe729br398",  # Existing chat
    assistantId="assistant_abc123",
    text="Tell me more"
)

Example - With Scope Rules:

message = unique_sdk.Space.create_message(
    user_id=user_id,
    company_id=company_id,
    assistantId="assistant_abc123",
    text="Search our engineering docs",
    toolChoices=["InternalSearch"],
    scopeRules={
        "or": [
            {
                "operator": "contains",
                "path": ["folderIdPath"],
                "value": "uniquepathid://scope_engineering_docs"
            }
        ]
    }
)

unique_sdk.Space.get_chat_messages - Get paginated messages

Compatibility

Compatible with release >.48

Get paginated messages from a space chat.

Parameters:

• chat_id (str, required) - Chat ID to retrieve messages from
• skip (int, optional) - Number of messages to skip (default: 0)
• take (int, optional) - Number of messages to return (default: 10, max: 100)

Returns:

Returns a GetAllMessagesResponse object.

messages = unique_sdk.Space.get_chat_messages(
    user_id=user_id,
    company_id=company_id,
    chat_id="chat_dejfhe729br398",
    skip=0,
    take=50
)

for msg in messages.data:
    print(f"{msg.role}: {msg.text}")

unique_sdk.Space.get_latest_message - Get most recent message

Get the most recent message in a space chat.

Parameters:

• chat_id (str, required) - Chat ID to get latest message from

Returns:

Returns a Space.Message object.

Example:

message = unique_sdk.Space.get_latest_message(
    user_id=user_id,
    company_id=company_id,
    chat_id="chat_dejfhe729br398"
)

print(f"Latest: {message.text}")

unique_sdk.Space.get_space - Get space configuration

Compatibility

Compatible with release >.48

Get detailed space configuration including modules and scope rules.

Parameters:

• space_id (str, required) - Space/assistant ID

Returns:

Returns a Space object.

Example:

space = unique_sdk.Space.get_space(
    user_id=user_id,
    company_id=company_id,
    space_id="assistant_hjcdga64bkcjnhu4"
)

print(f"Space: {space.name}")
print(f"Modules: {space.modules}")
print(f"Scope Rules: {space.scopeRules}")

unique_sdk.Space.delete_chat - Delete a chat

Delete a chat by ID.

Parameters:

• chat_id (str, required) - Chat ID to delete

Returns:

Returns a DeleteChatResponse object.

Example:

unique_sdk.Space.delete_chat(
    user_id=user_id,
    company_id=company_id,
    chat_id="chat_dejfhe729br398"
)

unique_sdk.Space.delete_space - Delete a space

Delete a space (assistant) by ID. Requires manage access to the space. (compatible with release > 2026.06)

Parameters:

• space_id (str, required) - Space/assistant ID to delete

Returns:

Returns a DeleteSpaceResponse object.

Example:

result = unique_sdk.Space.delete_space(
    user_id=user_id,
    company_id=company_id,
    space_id="assistant_hjcdga64bkcjnhu4"
)

print(f"Deleted space: {result['id']}")

Use Cases

Chat Against File

from unique_sdk.utils.chat_in_space import chat_against_file

async def process_document(file_path):
    """Upload and chat with a document."""
    result = await chat_against_file(
        user_id=user_id,
        company_id=company_id,
        assistant_id="assistant_abc123",
        path_to_file=file_path,
        displayed_filename="report.pdf",
        mime_type="application/pdf",
        text="Summarize the key findings",
        should_delete_chat=True  # Clean up after
    )

    return result.text

# Usage
import asyncio
summary = asyncio.run(process_document("/path/to/report.pdf"))

Wait for Response

from unique_sdk.utils.chat_in_space import send_message_and_wait_for_completion

async def get_space_response(assistant_id, question):
    """Send message and wait for completion."""
    message = await send_message_and_wait_for_completion(
        user_id=user_id,
        company_id=company_id,
        assistant_id=assistant_id,
        text=question,
        tool_choices=["WebSearch", "InternalSearch"],
        poll_interval=2,  # Check every 2 seconds
        max_wait=120,  # Wait up to 2 minutes
        stop_condition="completedAt"  # Wait for full completion
    )

    return message.text

# Usage
import asyncio
answer = asyncio.run(
    get_space_response(
        "assistant_abc123",
        "What are the latest developments in AI?"
    )
)

Scoped Search

def search_department_docs(assistant_id, query, department_scope):
    """Search specific department documents."""
    message = unique_sdk.Space.create_message(
        user_id=user_id,
        company_id=company_id,
        assistantId=assistant_id,
        text=query,
        toolChoices=["InternalSearch"],
        scopeRules={
            "or": [
                {
                    "operator": "contains",
                    "path": ["folderIdPath"],
                    "value": f"uniquepathid://{department_scope}"
                }
            ]
        }
    )

    return message

# Search engineering docs only
result = search_department_docs(
    "assistant_abc123",
    "API documentation",
    "scope_engineering_123"
)

Return Types

Space.Message

The Space.Message object represents a message in a space chat

Fields:

• id (str) - Unique message identifier
• chatId (str) - Chat ID containing the message
• text (str | None) - Message text content
• originalText (str | None) - Original message text before processing
• role (Literal["SYSTEM", "USER", "ASSISTANT"]) - Message role
• gptRequest (Dict[str, Any] | None) - GPT request data
• debugInfo (Dict[str, Any] | None) - Debug information dictionary
• completedAt (str | None) - Completion timestamp (ISO 8601)
• createdAt (str | None) - Creation timestamp (ISO 8601)
• updatedAt (str | None) - Last update timestamp (ISO 8601)
• startedStreamingAt (str | None) - When streaming started (ISO 8601)
• stoppedStreamingAt (str | None) - When streaming stopped (ISO 8601)
• references (List[Reference] | None) - List of source references. See Space.Reference for structure.
• assessment (List[Assessment] | None) - List of message assessments. See Space.Assessment for structure.

Returned by: Space.create_message(), Space.get_latest_message()

Space.Reference

The Space.Reference type defines source reference information for messages

Fields:

• name (str) - Reference name/title
• description (str | None) - Reference description
• url (str | None) - Reference URL
• sequenceNumber (int) - Sequence number for ordering references
• originalIndex (list[int] | None) - Original index positions
• sourceId (str) - Source identifier
• source (str) - Source name/path

Used in: Space.Message.references

Space.Assessment

The Space.Assessment type defines assessment information for messages

Fields:

• id (str) - Unique assessment identifier
• createdAt (str) - Creation timestamp (ISO 8601)
• updatedAt (str) - Last update timestamp (ISO 8601)
• messageId (str) - Associated message ID
• status (str) - Assessment status
• explanation (str | None) - Assessment explanation
• label (str | None) - Assessment label
• type (str | None) - Assessment type
• title (str | None) - Assessment title
• companyId (str) - Company ID
• userId (str) - User ID
• isVisible (bool) - Whether assessment is visible
• createdBy (str | None) - Creator user ID

Used in: Space.Message.assessment

GetAllMessagesResponse

The GetAllMessagesResponse object contains paginated messages

Fields:

• messages (List[Space.Message]) - List of message objects
• totalCount (int) - Total number of messages in chat

Returned by: Space.get_chat_messages()

Space

The Space object represents a conversational space/assistant

Fields:

• id (str) - Unique space identifier
• name (str) - Space name
• defaultForCompanyId (str | None) - Default company ID
• title (str | None) - Space title
• subtitle (str | None) - Space subtitle
• explanation (str | None) - Space explanation
• alert (str | None) - Alert message
• inputLimit (int | None) - Input character limit
• inputPlaceholder (str | None) - Input placeholder text
• chatUpload (str) - Chat upload configuration
• goals (List[str]) - List of space goals
• languageModel (str | None) - Language model identifier
• fallbackModule (str) - Fallback module identifier
• access (List[str]) - Access control list
• isExternal (bool) - Whether space is external
• isPinned (bool) - Whether space is pinned
• uiType (str) - UI type identifier
• settings (Dict[str, Any] | None) - Space settings
• assistantMcpServers (List[AssistantMcpServer]) - List of MCP servers. See Space.AssistantMcpServer for structure.
• modules (List[Module]) - List of configured modules. See Space.Module for structure.
• scopeRules (List[ScopeRule]) - List of scope rules. See Space.ScopeRule for structure.
• assistantAccess (List[AssistantAccess]) - List of access controls. See Space.AssistantAccess for structure.
• createdAt (str) - Creation timestamp (ISO 8601)
• updatedAt (str) - Last update timestamp (ISO 8601)

Returned by: Space.get_space(), Space.create_space()

SpaceAccessResponse

The SpaceAccessResponse object contains access entries for a space

Fields:

• access (List[AssistantAccess]) - List of access control entries. See Space.AssistantAccess for structure.

Returned by: Space.get_space_access()

AddSpaceAccessResponse

The AddSpaceAccessResponse object contains the added access entries

Fields:

• access (List[AssistantAccess]) - List of added access control entries. See Space.AssistantAccess for structure.

Returned by: Space.add_space_access()

DeleteSpaceAccessResponse

The DeleteSpaceAccessResponse object indicates success of deletion

Fields:

• success (bool) - Whether the deletion was successful

Returned by: Space.delete_space_access()

Space.AssistantMcpServer

The Space.AssistantMcpServer object represents an MCP server associated with a space

Fields:

• id (str) - Unique MCP server association identifier
• name (str) - MCP server name
• assistantId (str) - Associated assistant/space ID
• mcpServerId (str) - MCP server ID
• isEnabled (bool) - Whether the MCP server is enabled
• createdAt (str) - Creation timestamp (ISO 8601)
• updatedAt (str) - Last update timestamp (ISO 8601)

Used in: Space.assistantMcpServers

Space.Module

The Space.Module object represents a module configured for a space

Fields:

• id (str) - Unique module identifier
• name (str) - Module name
• description (str | None) - Module description
• toolDefinition (Dict[str, Any] | None) - Tool definition dictionary
• configuration (Dict[str, Any]) - Module configuration dictionary
• assistantId (str) - Associated assistant/space ID
• weight (int) - Module weight/priority
• isExternal (bool) - Whether module is external
• isCustomInstructionEnabled (bool) - Whether custom instructions are enabled
• moduleTemplateId (str | None) - Module template ID
• createdAt (str) - Creation timestamp (ISO 8601)
• updatedAt (str) - Last update timestamp (ISO 8601)

Used in: Space.modules

Space.ScopeRule

The Space.ScopeRule object represents a scope rule for a space

Fields:

• id (str) - Unique scope rule identifier
• assistantId (str) - Associated assistant/space ID
• title (str) - Scope rule title
• companyId (str) - Company ID
• rule (Dict[str, Any]) - UniqueQL rule definition
• isAdvanced (bool) - Whether rule uses advanced syntax
• createdAt (str) - Creation timestamp (ISO 8601)
• updatedAt (str) - Last update timestamp (ISO 8601)

Used in: Space.scopeRules

Space.AssistantAccess

The Space.AssistantAccess object represents access control for a space

Fields:

• id (str) - Unique access control identifier
• entityId (str) - User or group ID
• entityType (str) - Entity type ("USER" or "GROUP")
• type (str) - Access type ("USE", "MANAGE", or "UPLOAD")

Used in: Space.assistantAccess, SpaceAccessResponse.access, AddSpaceAccessResponse.access

DeleteChatResponse

The DeleteChatResponse object contains the deleted chat ID

Fields:

• chat_id (str) - ID of the deleted chat

Returned by: Space.delete_chat()

DeleteSpaceResponse

The DeleteSpaceResponse object contains the deleted space ID

Fields:

• id (str) - ID of the deleted space

Returned by: Space.delete_space()

Related Resources

• Message API - Direct message management
• Chat in Space Utility - Helper functions
• UniqueQL - Scope rule filtering