> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model access

> Read and manage which models your org can use, its default, provider and fallback routing.

Read and manage your org's model governance: the allow-list of enabled models, the default model, disabled providers, and fallback routing. This is the same governance the in-app `Settings → AI Workspace → Models` page manages, and it is enforced identically on every surface. Reads require `models.read`; the update requires `models.write` (both included in `control:read`).

Access carries no plan-tier floor: premium models are off by default to prevent cost surprises, and any tier can enable any model by adding its id to `allowed_model_ids`. Use [Models](/ai-api/control/models) to discover ids and their `default_off`/`premium` state.

<Note>
  This endpoint manages the API-accessible slice of your model configuration. Model ids that are not API-accessible — enabled in-app or referenced in a fallback chain — are preserved untouched by updates here and are not shown in `allowed_model_ids` or `fallback_chain`. `fallback_chain` is returned only when `fallback_mode` is `manual`.
</Note>

***

## Get model access

```
GET https://api.usehasp.com/v1/model-access
Authorization: Bearer hasp_api_live_...
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "allowed_model_ids": ["claude-haiku-4-5", "claude-sonnet-4-6"],
    "default_model_id": "claude-sonnet-4-6",
    "disallowed_providers": [],
    "fallback_mode": "auto",
    "fallback_chain": []
  }
}
```

### Fields

| Field                  | Description                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `allowed_model_ids`    | Models your org has enabled for inference.                                                                          |
| `default_model_id`     | The model used when a request does not specify one.                                                                 |
| `disallowed_providers` | Providers blocked for your org. A model whose provider is disallowed is unreachable even if in `allowed_model_ids`. |
| `fallback_mode`        | `off`, `auto`, or `manual`. Controls what happens when the requested model is unavailable.                          |
| `fallback_chain`       | In `manual` mode, the ordered list of models to fall back to. Empty otherwise.                                      |

***

## Update model access

```
PATCH https://api.usehasp.com/v1/model-access
Authorization: Bearer hasp_api_live_...
Content-Type: application/json
```

All fields are optional. Send only what you want to change. An empty body returns the current state without modifying anything.

### Body

```json theme={null}
{
  "allowed_model_ids": ["claude-sonnet-4-6", "claude-opus-4-7"],
  "default_model_id": "claude-sonnet-4-6",
  "disallowed_providers": [],
  "fallback_mode": "auto",
  "fallback_chain": []
}
```

| Field                  | Type   | Description                                                                                                                                                        |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `allowed_model_ids`    | array  | Model ids to enable. Each must be an API-accessible model id (see [Models](/ai-api/control/models)).                                                               |
| `default_model_id`     | string | Must be one of the enabled models, and its provider must not be disallowed.                                                                                        |
| `disallowed_providers` | array  | Provider slugs to block. The default model's provider cannot be disallowed.                                                                                        |
| `fallback_mode`        | string | `off`, `auto`, or `manual`.                                                                                                                                        |
| `fallback_chain`       | array  | Required and non-empty when `fallback_mode` is `manual`. Each entry must be enabled, not the default, and not from a disallowed provider. Ignored in `off`/`auto`. |

### Response

Returns the updated state in the same shape as the GET response. Changes are recorded in the audit log tagged `source: api`: `model_access.updated` when the enabled list, disallowed providers, or fallback routing change, and `model_access.default_changed` when the default model changes. A change to only the default model emits `model_access.default_changed` alone.

***

## Error codes

| Code                | HTTP | Description                                                                                                                                  |
| ------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_API_KEY`   | 401  | Invalid or revoked token                                                                                                                     |
| `MISSING_SCOPE`     | 403  | Key lacks `models.read`/`models.write` (`control:read`) scope                                                                                |
| `VALIDATION_FAILED` | 422  | Unknown or non-API model id; default not in the enabled list; default from a disallowed provider; `manual` mode with no valid fallback chain |