# Model Runtime API

The Model Runtime API manages model catalog records, artifacts, inference engines, and local model
services in the Node deployment.

These endpoints are unavailable in the Cloudflare runtime.

## Read Endpoints

```text
GET /v1/projects/:projectId/models/runtime
GET /v1/projects/:projectId/models/activity
GET /v1/projects/:projectId/models/catalog
GET /v1/projects/:projectId/models/:modelId
GET /v1/projects/:projectId/models/:modelId/profiles/:profileId
GET /v1/projects/:projectId/models/:modelId/huggingface-details
```

Reads require `workspace:read`. Catalog queries support search text, category, pipeline tag, format,
installed view, sorting, cursor, and limit fields.

## Catalog And Import

```text
POST /v1/projects/:projectId/models/catalog-refreshes
POST /v1/projects/:projectId/models/imports/huggingface
```

Import an exact Hugging Face repository:

```bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/models/imports/huggingface" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId": "mlx-community/gemma-4-e2b-it-4bit"}'
```

## Engines

```text
POST   /v1/projects/:projectId/models/engines/:engine/installations
DELETE /v1/projects/:projectId/models/engines/:engine/installations/:generation
DELETE /v1/projects/:projectId/models/engines/:engine
```

Engine installation is asynchronous unless the requested engine is already ready.

## Artifacts And Services

```text
POST   /v1/projects/:projectId/models/:modelId/profiles/:profileId/downloads
DELETE /v1/projects/:projectId/models/:modelId/profiles/:profileId/downloads/:generation
PUT    /v1/projects/:projectId/models/:modelId/profiles/:profileId/service
DELETE /v1/projects/:projectId/models/:modelId/profiles/:profileId/service
POST   /v1/projects/:projectId/models/:modelId/profiles/:profileId/trials
```

Downloads, engine installations, and service starts expose generation-aware state. Use the runtime
and activity endpoints to poll progress instead of assuming that an accepted request is complete.

Mutation endpoints require `models:manage` or the corresponding project model-management
permission.

See [AI Models](../ai-models/index.md), [Model runtime](../ai-models/runtime.md), and
[Models CLI](../cli/models.md).