AimableDocs
DocsAPI Reference

Space Allowed Models

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-proxy/v1/spaces/{space_id}/models

Example Request:

curl -X GET 'https://platform.aimable.ai/api-proxy/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):

{
  "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-proxy/v1/spaces/{space_id}/models

Example Request:

curl -X POST 'https://platform.aimable.ai/api-proxy/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):

{
  "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-proxy/v1/spaces/{space_id}/models/{tenant_model_id}

Example Request:

curl -X DELETE 'https://platform.aimable.ai/api-proxy/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:

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

  2. Add a new model using its tenant_model_id:

    POST /api-proxy/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:

    DELETE /api-proxy/v1/spaces/{space_id}/models/{tenant_model_id}

This flow ensures clean, auditable model governance.

Authentication & Error Handling

  • Authentication: All requests require a valid Authorization: Bearer <token> header.
  • API Key (Optional): Some deployments may require X-API-Key for additional access control.
  • Idempotency: Required for POST requests using the Idempotency-Key header.

Common Errors:

  • 401 Unauthorized: Missing or invalid access token.
  • 403 Forbidden: User lacks permissions for the space.
  • 422 Unprocessable Entity: Invalid input (e.g., malformed UUID). Check detail.loc and detail.msg.

Example error:

{
  "detail": [
    {
      "loc": ["path", "space_id"],
      "msg": "Input should be a valid UUID",
      "type": "uuid_parsing",
      "input": "not-a-uuid"
    }
  ]
}

Use these responses to validate inputs and improve client resilience.

Related Endpoints