AimableDocs
DocsAPI Reference

Tenant Models

Tenant Models API

The tenant-models domain in the Aimable Platform API allows tenants (organizations or users) to configure and manage their own AI model integrations. A tenant model represents a specific configuration of a base AI model (identified by model_id) paired with an API key, custom overrides, and a user-defined alias. This enables fine-grained control over model behavior, access, and routing within a tenant’s environment.

Tenant models are essential for customizing how AI requests are handled—such as routing to specific providers, applying rate limits, or overriding model parameters—without exposing low-level infrastructure details.

Key Concepts

  • tenant_model_id: A unique UUID identifying a specific tenant model configuration.
  • model_id: The ID of the base AI model (e.g., gpt-4-turbo, claude-3-opus) provided by the platform.
  • alias: A human-readable name (e.g., "customer-support-model") used to reference the model in your applications.
  • api_key_id: The ID of the API key used to authenticate requests to the underlying model provider.
  • overrides_json: Optional JSON object to override default model settings (e.g., {"temperature": 0.7, "max_tokens": 512}).
  • is_enabled: Boolean flag to enable or disable the model configuration.

All operations are scoped to the authenticated tenant and require appropriate permissions.

Common Workflows

1. List All Tenant Models

Retrieve existing model configurations with optional pagination.

curl -X GET "https://api.aimable.com/api-proxy/v1/tenant/models?limit=10" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: <optional-api-key>"

Sample Response (200 OK):

{
  "data": [
    {
      "id": "tm-abc123",
      "tenant_id": "t-xyz789",
      "alias": "summarization-model",
      "model_id": "m-def456",
      "model_display_name": "GPT-4 Turbo",
      "api_key_id": "ak-987xyz",
      "is_enabled": true,
      "overrides_json": { "max_tokens": 256 },
      "created_at": "2024-04-01T12:00:00Z",
      "updated_at": "2024-04-01T12:00:00Z"
    }
  ],
  "meta": {
    "next_cursor": "cursor_123",
    "has_more": false
  }
}

Use cursor and limit for paginated results.

2. Create a New Tenant Model

Register a new model configuration with an alias and optional overrides.

curl -X POST "https://api.aimable.com/api-proxy/v1/tenant/models" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Idempotency-Key: abc123-xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "m-gpt4-03",
    "alias": "chatbot-model",
    "api_key_id": "ak-secure123",
    "is_enabled": true,
    "overrides_json": {
      "temperature": 0.5,
      "top_p": 0.9
    }
  }'

✅ Idempotency: The Idempotency-Key header ensures safe retries.

Response (201 Created):

{
  "data": {
    "id": "tm-new456",
    "tenant_id": "t-xyz789",
    "alias": "chatbot-model",
    "model_id": "m-gpt4-03",
    "api_key_id": "ak-secure123",
    "is_enabled": true,
    "overrides_json": {
      "temperature": 0.5,
      "top_p": 0.9
    },
    "created_at": "2024-04-02T08:00:00Z",
    "updated_at": "2024-04-02T08:00:00Z"
  }
}

3. Update a Tenant Model

Modify an existing configuration, such as enabling/disabling or updating overrides.

curl -X PATCH "https://api.aimable.com/api-proxy/v1/tenant/models/tm-new456" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_enabled": false,
    "overrides_json": {
      "temperature": 0.9,
      "max_tokens": 1024
    }
  }'

Only changed fields need to be sent.

4. Retrieve or Delete a Model

Get a specific model:

curl -X GET "https://api.aimable.com/api-proxy/v1/tenant/models/tm-new456" \
  -H "Authorization: Bearer <your-access-token>"

Delete it (soft delete):

curl -X DELETE "https://api.aimable.com/api-proxy/v1/tenant/models/tm-new456" \
  -H "Authorization: Bearer <your-access-token>"

Both return the full model object, including deleted_at on deletion.

Authentication & Error Handling

  • Authentication: All requests require a valid Authorization: Bearer <token> header.
  • Optional X-API-Key: Used for additional context or integration-specific access control.
  • Idempotency: Required for POST requests using the Idempotency-Key header to prevent duplicate creations.

Common Errors

| Status | Meaning | |-------|--------| | 401 | Missing or invalid access token | | 403 | Insufficient permissions for the tenant | | 422 | Invalid input (e.g., malformed UUID, missing required field) |

Example 422 response:

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

Typical Workflow

  1. List existing models to check for duplicates.
  2. Create a new model with a unique alias and desired overrides.
  3. Update as needed (e.g., toggle is_enabled, adjust parameters).
  4. Delete when no longer in use.

These operations empower tenants to manage AI model configurations dynamically, supporting use cases like A/B testing, environment-specific settings, and secure key management.

Related Endpoints