# AI Models

Endpoints for searching AI models and managing per-scope enablement. Models are catalog entries synced from models.dev. Use scope parameter with enable/disable endpoints to manage models per-scope.

## Search AI models

 - [GET /api/v1/ai-models](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models/get.md): Search and filter AI models with pagination. Returns models matching all specified criteria
with scoped enablement state.

Searching for embedding models with specific vector dimension:

For embedding models, the maxOutputTokens field in the model limits represents the embedding vector dimension
(e.g., 1536 for OpenAI ada-002, 3072 for text-embedding-3-large).

To find embedding models with a specific vector size, combine:
- capabilities=EMBEDDINGS - filter to embedding models only
- minMaxOutputTokens and maxMaxOutputTokens set to the desired dimension

Example: To find embedding models with 1536-dimensional vectors:
?scope=global&capabilities=EMBEDDINGS&minMaxOutputTokens=1536&maxMaxOutputTokens=1536

RBAC:
- requires ANY of AIModels.Read, GroupAIModels.Read

## Get an AI model

 - [GET /api/v1/ai-models/{modelId}](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D/get.md): Returns a single AI model by ID with scoped enablement state.

RBAC:
- requires ANY of AIModels.Read, GroupAIModels.Read

## List agents using scoped model configuration

 - [GET /api/v1/ai-models/{modelId}/agents](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D~1agents/get.md): Returns AI agents that currently reference this model's scoped configuration in the given scope.

RBAC:
- requires ANY of AIModels.Manage, GroupAIModels.Manage

## Remove scoped model configuration

 - [DELETE /api/v1/ai-models/{modelId}/configure](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D~1configure/delete.md): Removes scoped model enablement/configuration row for the model in the specified scope.

RBAC:
- requires ANY of AIModels.Manage, GroupAIModels.Manage

## Disable a model in a scope

 - [PUT /api/v1/ai-models/{modelId}/disable](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D~1disable/put.md): Disables a model in the specified scope.

RBAC:
- requires ANY of AIModels.Manage, GroupAIModels.Manage

## Enable a model in a scope

 - [PUT /api/v1/ai-models/{modelId}/enable](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D~1enable/put.md): Enables a model for use in the specified scope. Requires the provider to be configured with a valid API key in that scope.

RBAC:
- requires ANY of AIModels.Manage, GroupAIModels.Manage

## Get model migration path

 - [GET /api/v1/ai-models/{modelId}/migration-path](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D~1migration-path/get.md): Returns the chain of models from the given model to the final active successor. Catalog-only, no scope needed.

RBAC:
- requires ANY of AIModels.Read, GroupAIModels.Read

## Resolve an AI model

 - [GET /api/v1/ai-models/{modelId}/resolve](https://docs.wellesley.social/openapi/ai-models/paths/~1api~1v1~1ai-models~1%7Bmodelid%7D~1resolve/get.md): Resolves a model by following the successor chain if deprecated. Returns the active model that should be used. Catalog-only, no scope needed.

RBAC:
- requires ANY of AIModels.Read, GroupAIModels.Read