Model Library

The model library is the set of MLX repos cached on the hosts you select. It is not a fixed list of models that every Mac has installed.

Models on your hosts

GET /api/v1/models needs a bearer token and a hosts query of one or more host UUIDs (50 maximum). A host is included only when it is active and has sent a heartbeat in the last two minutes. An empty hosts value returns 400.

HTTP
GET /api/v1/models?hosts=HOST_UUID
Authorization: Bearer mc_your_key

Each model includes:

repo_id, such as mlx-community/Llama-3.2-1B. This is the model_id you send when you create a job.
size_bytes and host_count
runnable and runnable_hosts. A model marked not runnable includes unsupported_reason.
loaded when a selected host is already running that repo
removable on a host when you downloaded the copy that is cached there
chips, regions, memory_gb, and the hosts that have it cached

meta.online is how many of the selected hosts answered. meta.offline lists the selected UUIDs that did not. Loaded models are listed first.

Search

GET /api/v1/models/search?hosts=HOST_UUID&q=llama searches public Hugging Face repos and keeps MLX models: ids under mlx-community/, library name mlx, or an mlx tag. Private and gated repos are left out. Each result has repo_id, downloads, likes, warm_hosts, and cached when a selected host can already run it.

To cache a repo on a machine you control, POST /api/v1/hosts/{uuid}/model-downloads with {"repo_id": "org/name"}. Poll GET /api/v1/model-downloads/{download_id}, or cancel with POST /api/v1/model-downloads/{download_id}/cancel.

To delete a copy you downloaded, POST /api/v1/hosts/{uuid}/model-removals with the same body. That works only when the latest completed download of that repo on that host is yours. A model the host already had, or one someone else downloaded, stays where it is. A job that is assigned or running that model on the host has to finish first. Poll GET /api/v1/model-removals/{removal_id}.

Context length

GET /api/v1/models/context?repo_id=org/name reads the context length from that model's config.json. The response is repo_id and context_length. If the model does not publish a length, the route returns 404.

Use the repo id on the job

Pass repo_id as model_id on client.jobs.submit. A host that has the repo marked not runnable is not chosen for that job. See the MLX guide for the inference call.