AimableDocs
DocsAPI ReferenceRelease Notes

Space Allowed Models

Updated 9 July 2026

Space Allowed Models

The space-allowed-models domain in the Aimable Platform API (v0.1.0) enables you to manage which AI models are accessible within a specific space. A space represents a logical environment—such as a workspace or project—where users interact with AI capabilities. By controlling the allowed models, administrators can enforce security policies, optimize costs, and ensure compliance by restricting model access to approved options.

This API domain lets you list, add, and remove models that are permitted for use in a given space. Each entry includes metadata such as alias, capabilities, and activation status, giving fine-grained control over the AI experience.

Key Concepts

  • Space (space_id): A unique identifier (UUID) representing a logical container for AI interactions.
  • Tenant Model (tenant_model_id): A model registered under your tenant, previously created via model management APIs. This is the reference used when allowing models in a space.
  • Allowed Model: A model enabled for use in a specific space. It may be enabled/disabled or set as default.
  • Idempotency-Key: Required for POST requests to ensure safe retries without duplicating entries.

How to Use the Endpoints

1. List Allowed Models in a Space

Retrieve all models currently allowed in a space, with optional pagination.

Endpoint:
GET /api/v1/spaces/{space_id}/models

Example Request:

bash
curl -X GET 'https://platform.aimable.ai/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/models?limit=5' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'X-API-Key: your-api-key'

Response (200 OK):

json
{
  "data": [
    {
      "tenant_model_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "alias": "gpt-4-turbo",
      "is_enabled": true,
      "is_default": true,
      "context_window": 128000,
      "capabilities": ["chat", "reasoning"],
      "reasoning": { "enabled": true },
      "logo_url": "https://cdn.aimable.ai/models/gpt4-light.png",
      "logo_url_dark": "https://cdn.aimable.ai/models/gpt4-dark.png",
      "added_at": "2024-04-01T12:00:00Z"
    }
  ],
  "meta": {
    "next_cursor": "abc123",
    "has_more": false
  }
}

Use cursor and limit for paginated results.

2. Add a Model to a Space

Enable a tenant model for use in a space.

Endpoint:
POST /api/v1/spaces/{space_id}/models

Example Request:

bash
curl -X POST 'https://platform.aimable.ai/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/models' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Idempotency-Key: abcdef-123456' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_model_id": "a1b2c3d4-5678-9012-3456-789012345678"
  }'

Response (201 Created):

json
{
  "data": {
    "tenant_model_id": "a1b2c3d4-5678-9012-3456-789012345678",
    "alias": "claude-3-opus",
    "is_enabled": true,
    "is_default": false,
    "context_window": 200000,
    "capabilities": ["chat", "file-processing"],
    "added_at": "2024-04-01T12:05:00Z"
  }
}

The Idempotency-Key ensures that retrying the request won’t add the same model twice.

3. Remove a Model from a Space

Revoke access to a model in a space.

Endpoint:
DELETE /api/v1/spaces/{space_id}/models/{tenant_model_id}

Example Request:

bash
curl -X DELETE 'https://platform.aimable.ai/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/models/a1b2c3d4-5678-9012-3456-789012345678' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'X-API-Key: your-api-key'

Response (204 No Content):
No body returned on success.

Common Workflow

Here’s a typical sequence to configure a space with specific models:

  1. List current models to see what's already allowed:

    bash
    GET /api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/models

  2. Add a new model using its tenant_model_id:

    bash
    POST /api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/models

  3. Verify the addition by listing again or checking the response.

  4. Remove outdated models if needed:

    bash
    DELETE /api/v1/spaces/{space_id}/models/{tenant_model_id}

This flow ensures clean, auditable model governance.

See Authentication & errors for request authentication and the standard error responses.

Related Endpoints

See also