AimableDocs
DocsAPI Reference

Spaces

Spaces API

A Space in the Aimable Platform represents a dedicated environment where AI interactions occur. Spaces define the behavior, appearance, and capabilities of AI agents, including the models used, tools enabled, and data handling rules. They are essential for organizing and customizing AI experiences across different use cases—such as customer support, internal knowledge assistants, or public chatbots.

Each Space has a unique ID and can be customized with a name, description, avatar, system prompts, and privacy settings like PII (Personally Identifiable Information) and OII (Other Identifiable Information) pseudonymization.

Key Concepts

  • Space: A configurable AI environment with its own settings, tools, and identity.
  • space_id: A UUID identifying a specific Space. Used in all Space-specific endpoints.
  • Settings: Includes model selection, enabled tools, system prompts, and data privacy rules.
  • Authentication: All endpoints require a valid X-API-Key header for access control.

How to Use the Spaces API

1. List All Spaces

Retrieve a list of all available Spaces.

curl -X GET "https://api.aimable.com/api-proxy/v1/spaces" \
  -H "X-API-Key: your_api_key_here"

Response (200 OK):

[
  {
    "space_id": "a1b2c3d4-1234-5678-9012-abcdef123456",
    "name": "Customer Support Bot",
    "description": "Handles customer inquiries about orders and returns.",
    "avatar_url": "https://cdn.aimable.com/avatars/support-bot.png",
    "apply_pii_pseudonymization": true
  }
]

2. Create a New Space

Create a Space with custom settings.

curl -X POST "https://api.aimable.com/api-proxy/v1/spaces" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR Assistant",
    "description": "Internal assistant for employee HR queries",
    "apply_pii_pseudonymization": true,
    "enabled_tools": ["document_search", "calendar_access"]
  }'

Response (201 Created):

{
  "space_id": "e5f6g7h8-3456-7890-abcd-efgh78901234",
  "name": "HR Assistant",
  "description": "Internal assistant for employee HR queries",
  "apply_pii_pseudonymization": true,
  "enabled_tools": ["document_search", "calendar_access"]
}

3. Get a Specific Space

Fetch details of a single Space by its ID.

curl -X GET "https://api.aimable.com/api-proxy/v1/spaces/e5f6g7h8-3456-7890-abcd-efgh78901234" \
  -H "X-API-Key: your_api_key_here"

Response (200 OK):

{
  "space_id": "e5f6g7h8-3456-7890-abcd-efgh78901234",
  "name": "HR Assistant",
  "description": "Internal assistant for employee HR queries",
  "enabled_tools": ["document_search", "calendar_access"],
  "apply_pii_pseudonymization": true
}

4. Update a Space

Modify an existing Space’s configuration.

curl -X PATCH "https://api.aimable.com/api-proxy/v1/spaces/e5f6g7h8-3456-7890-abcd-efgh78901234" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated to include benefits and onboarding support.",
    "apply_oii_pseudonymization": true
  }'

Response (200 OK):

{
  "space_id": "e5f6g7h8-3456-7890-abcd-efgh78901234",
  "name": "HR Assistant",
  "description": "Updated to include benefits and onboarding support.",
  "apply_pii_pseudonymization": true,
  "apply_oii_pseudonymization": true
}

5. Delete a Space

Remove a Space permanently.

curl -X DELETE "https://api.aimable.com/api-proxy/v1/spaces/e5f6g7h8-3456-7890-abcd-efgh78901234" \
  -H "X-API-Key: your_api_key_here"

Response (200 OK):

{
  "message": "Space deleted successfully"
}

6. Get Space Background Image

Retrieve the background image associated with a Space (e.g., for UI rendering).

curl -X GET "https://api.aimable.com/api-proxy/v1/spaces/e5f6g7h8-3456-7890-abcd-efgh78901234/background" \
  -H "X-API-Key: your_api_key_here"

Response (200 OK): Returns image data (binary) with appropriate Content-Type.

Common Workflows

Create and Configure a New AI Assistant

  1. Create a new Space:

    POST /v1/spaces
{ "name": "IT Helpdesk Bot" }

  2. Update it with tools and privacy settings:

    PATCH /v1/spaces/{space_id}
{ "enabled_tools": ["ticketing_system"], "apply_pii_pseudonymization": true }

  3. Retrieve the Space to confirm settings:

    GET /v1/spaces/{space_id}

  4. Optionally, fetch background image for frontend display:

    GET /v1/spaces/{space_id}/background

Authentication & Error Handling

  • Authentication: All requests require the X-API-Key header.
  • Error Responses:
    • 401 Unauthorized: Invalid or missing API key.
    • 403 Forbidden: Insufficient permissions.
    • 422 Unprocessable Entity: Invalid input (e.g., malformed space_id or missing required fields).

Example 422 response:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}

Always validate inputs and ensure the X-API-Key is included. Use UUIDs correctly for space_id parameters.

Related Endpoints