Space Model Policy

Updated 9 July 2026

Space Model Policy

The space-model-policy domain in the Aimable Platform API (v0.1.0) governs how AI models are selected and routed within a space—a logical container for AI interactions. This policy determines the default model, routing behavior, and mode of operation for all model invocations in that space. It ensures consistent, secure, and predictable model usage without requiring clients to specify models on every request.

This is essential for teams that want to:

Enforce a default model across all applications in a space
Control model access and routing logic centrally
Switch underlying models seamlessly without client changes

Key Concepts

space_id: A UUID identifying the space. All model policies are scoped to a space.
mode: The operational mode (e.g., "fixed", "dynamic"). Determines how models are selected.
default_model_id: The UUID of the default model used when no specific model is requested.
default_model_alias: A human-readable name for the default model (e.g., "gpt-4-turbo").
routing_strategy: Optional configuration for advanced routing (e.g., load balancing or failover rules).

Note: The API never exposes provider_model_id directly—this is abstracted for security and flexibility.

How to Use the Endpoints

1. Get the Current Model Policy

Use GET /v1/spaces/{space_id}/model-policy to retrieve the current model configuration.

Example Request:

bash

curl -X GET "https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/model-policy" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: your-api-key"

Example Response (200 OK):

json

{
  "data": {
    "space_id": "123e4567-e89b-12d3-a456-426614174000",
    "mode": "fixed",
    "default_model_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "default_model_alias": "gpt-4-turbo",
    "routing_strategy": null,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-20T14:30:00Z"
  }
}

2. Set or Update the Model Policy

Use PUT /v1/spaces/{space_id}/model-policy to define or change the model policy.

Example Request:

bash

curl -X PUT "https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/model-policy" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fixed",
    "default_model_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "routing_strategy": {
      "type": "failover",
      "models": [
        "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4g5h"
      ]
    }
  }'

Example Response (200 OK):

json

{
  "data": {
    "space_id": "123e4567-e89b-12d3-a456-426614174000",
    "mode": "fixed",
    "default_model_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "default_model_alias": "gpt-4-turbo",
    "routing_strategy": {
      "type": "failover",
      "models": [
        "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4g5h"
      ]
    },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-02-01T09:15:00Z"
  }
}

The default_model_alias is automatically resolved from the default_model_id—you don’t need to provide it in the request.

Typical Workflow

Retrieve current policy to inspect existing settings:

bash

GET /v1/spaces/123e4567-e89b-12d3-a456-426614174000/model-policy

Update the policy to switch to a new default model:

bash

PUT /v1/spaces/123e4567-e89b-12d3-a456-426614174000/model-policy
{
  "mode": "fixed",
  "default_model_id": "new-model-uuid-here"
}

Verify the change by fetching the policy again.

This allows administrators to rotate models (e.g., from gpt-3.5-turbo to gpt-4) without modifying client applications.

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

By managing the space model policy, you centralize control over AI model usage—making your platform more secure, maintainable, and scalable.

GET /v1/spaces/{space_id}/model-policy — Get Space Model Policy
PUT /v1/spaces/{space_id}/model-policy — Set Space Model Policy

Space Model Policy