AimableDocs
DocsAPI Reference

Space Model Policy

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:

curl -X GET "https://api.aimable.com/api-proxy/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):

{
  "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:

curl -X PUT "https://api.aimable.com/api-proxy/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):

{
  "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

  1. Retrieve current policy to inspect existing settings:

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

  2. Update the policy to switch to a new default model:

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

  3. 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.

Authentication & Error Handling

  • Authentication: All requests require a valid Authorization: Bearer <token> header.
  • Optional API Key: Some deployments may also accept X-API-Key for additional access control.

Common Errors

| Status | Meaning | |-------|--------| | 401 Unauthorized | Missing or invalid access token | | 403 Forbidden | User lacks permission to manage this space | | 422 Unprocessable Entity | Invalid input (e.g., malformed UUID, missing mode) |

Example 422 Response:

{
  "detail": [
    {
      "loc": ["body", "default_model_id"],
      "msg": "value is not a valid uuid",
      "type": "value_error.uuid"
    }
  ]
}

Always validate your space_id and default_model_id as UUIDs, and ensure mode is a supported string (e.g., "fixed").

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

Related Endpoints