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

# Inference deployments API

> Create and manage dedicated inference deployments of catalog models and training checkpoints.

Deployment management uses `https://api.primeintellect.ai/api/v1/inference`. Requests authenticate with `Authorization: Bearer <API_KEY>`. Reads require `factory:read`, and mutations require `factory:write`.

Chat completions use a separate base URL, returned as `endpointUrl`, and require **Inference** permission. The request's `model` is the deployment's `servedModelAlias`. See [Send a request](https://docs.primeintellect.ai/inference/dedicated-deployments.md#send-a-request).

## Endpoints

All paths below are relative to `https://api.primeintellect.ai/api/v1`.

| Method | Path | Result |
| - | - | - |
| `GET` | `/inference/catalog` | Deployable models and team cluster capabilities. |
| `POST` | `/inference/deploy` | `202` with a catalog deployment. |
| `POST` | `/inference/checkpoint-deploy` | `202` with a checkpoint deployment, reusing an existing live deployment when present. |
| `GET` | `/inference/deployments` | `{data: [...]}` containing deployments visible in the requested account. |
| `GET` | `/inference/deployments/{deployment_id}` | One deployment. |
| `POST` | `/inference/deployments/{deployment_id}/scale` | `202` with the deployment after accepting the desired replica count. |
| `DELETE` | `/inference/deployments/{deployment_id}` | `202` with the deployment in `TERMINATING` state. |

## Catalog and account selection

`GET /inference/catalog` accepts optional `teamId` and `primeClusterId` query parameters. With `teamId`, it returns the team's clusters and the models each can serve. `primeClusterId` filters models to one of those clusters. Without `teamId`, the response contains models for personal on-demand deployment and no team clusters.

The response contains `models` and `clusters` arrays. A model's `id` is the value accepted as `modelCatalogId`. Each cluster's `primeClusterId` identifies a placement, `gatewayReady` reports gateway readiness, and `modelGpus` maps supported catalog IDs to GPUs per replica.

`GET /inference/deployments?teamId=<team-id>` lists team deployments. Without `teamId`, it lists the caller's personal deployments. Team members can read their team's deployments.

Management requests select the account through `teamId`. The `X-Prime-Team-ID` header used for model requests does not replace that field.

## Deploy a catalog model

`POST /inference/deploy` accepts:

| Field | Required | Meaning |
| - | - | - |
| `modelCatalogId` | Yes | Model ID from the deployment catalog. |
| `teamId` | No | Owning and paying team. Omitted for a personal on-demand deployment. |
| `primeClusterId` | No | Team cluster to serve on. Omitted for Prime's on-demand pool. |
| `deploymentName` | No | Generated when omitted. At most 29 characters, matching `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`. |
| `replicas` | No | Initial replica count, `1` through `4`. Defaults to `1`. |

Team catalog deployments require a team admin. Team-cluster placement requires ownership of the cluster and enabled self-service inference. On-demand deployments require wallet admission and pool capacity.

```bash theme={null}
curl https://api.primeintellect.ai/api/v1/inference/deploy \
  -H "Authorization: Bearer $PRIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelCatalogId": "<model-catalog-id>",
    "teamId": "<team-id>",
    "deploymentName": "my-endpoint",
    "replicas": 1
  }'
```

## Deploy a checkpoint

`POST /inference/checkpoint-deploy` accepts:

| Field | Required | Meaning |
| - | - | - |
| `runId` | Yes | Accessible training run that belongs to a team. |
| `step` | Yes | Nonnegative step with an available `READY` checkpoint. |
| `teamId` | No | Defaults to the run's team. Must match that team. |
| `onDemand` | No | `true` selects Prime's pool. `false` selects the run's own team cluster. Omitted selects that cluster if the team still owns it, otherwise on-demand capacity. |
| `replicas` | No | Initial on-demand replica count, `1` through `4`. Defaults to `1`. A deployment on the run's own cluster starts with one replica. |

Any run-team member can start an on-demand checkpoint deployment. Deployment on the run's own cluster requires a cluster-team admin. The base model needs an inference catalog serving configuration.

A repeated request for the same run and step returns the existing pending, deploying, or running deployment. That existing deployment is returned even if the new request specifies different placement or replica options.

```bash theme={null}
curl https://api.primeintellect.ai/api/v1/inference/checkpoint-deploy \
  -H "Authorization: Bearer $PRIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runId": "<run-id>", "step": 100, "onDemand": true, "replicas": 1}'
```

## Scale and delete

The scale request body is `{"replicas": 2}`. The schema accepts integers from `1` through `32`. The deployment's `maxReplicas`, account limits, and capacity can impose a lower limit. Only `RUNNING` deployments can be scaled. Any member of the owning team, or the owner of a personal deployment, can scale it. On-demand scale-ups reserve and bill additional GPUs.

Deletion accepts no body. A team admin or the creator, while still a member, can delete a team deployment. Only the owner can delete a personal deployment. Deletion stops serving and releases GPUs without deleting the source training checkpoint.

## Deployment response

Create, get, scale, and delete return the same deployment schema. List wraps deployment objects in `data`.

| Field | Meaning |
| - | - |
| `id`, `deploymentName` | Deployment ID and display name. |
| `status` | Lifecycle status, including `PENDING`, `DEPLOYING`, `RUNNING`, `FAILED`, and `TERMINATING`. |
| `statusPhase`, `errorMessage` | Nullable startup phase and error detail. |
| `servedModelAlias` | Model identifier for requests to this deployment. |
| `endpointUrl` | OpenAI-compatible base URL, populated only when `RUNNING`. |
| `checkpoint` | Nullable `{runId, step}` identifying the source checkpoint. |
| `isOnDemand` | Whether the deployment uses the on-demand pool. |
| `replicas`, `gpusPerReplica`, `maxReplicas` | Nullable desired replica count, GPUs per replica, and replica cap. |
| `scaleState` | Nullable state of replica convergence. An accepted request does not imply ready workers. |
| `createdAt`, `dashboardUrl` | Creation timestamp and endpoint page URL. |

A `202` response acknowledges the request. It does not mean deployment, scaling, or deletion has completed. The deployment continues after the client disconnects.

## Errors

| Status | Meaning |
| - | - |
| `400` | A request the schema accepts but the service cannot honor: an unknown catalog ID, a scale above the configured replica cap, or a cluster that is not inference-enabled or not owned by a team. |
| `401` | Missing or invalid API credentials, or a key without the required scope. |
| `402` | Insufficient balance for on-demand admission. |
| `403` | Team membership or role, model access, account eligibility, or disabled self-service access. |
| `404` | Requested resource is absent or not visible to the caller. |
| `409` | Deployment conflict, unavailable capacity, unavailable checkpoint serving configuration, or incompatible lifecycle state. |
| `422` | Request does not match the schema, such as a missing step or an invalid replica count. |

Error details describe the specific refusal. See [Troubleshooting](https://docs.primeintellect.ai/inference/troubleshooting.md) for recovery steps and the [production OpenAPI schema](https://api.primeintellect.ai/openapi.json) for generated request and response definitions.
