---
title: "/v1/endpoints"
description: "Create, list, retrieve, update, suspend, resume, and delete dedicated endpoints."
section: api-reference
order: 7
layout: api-reference
updated: "2026-08-03"
---

Manage dedicated endpoints directly over HTTP — the same resource the console's [Endpoints](/endpoints) page manages, without a browser in the loop. List, create, inspect, rescale, suspend, resume, and delete them. Once an endpoint exists you call it through `/v1/chat/completions` like any other model — see [Call a dedicated endpoint](/docs/dedicated-endpoints/call-endpoint).

For the concepts behind these calls — what a flavor is, how autoscaling works, what each lifecycle action does — see [What are Dedicated Endpoints?](/docs/dedicated-endpoints/what-are-dedicated-endpoints) and the rest of that section. This page is the wire contract.

The lifecycle actions documented here are **suspend** and **resume**. Suspending and then resuming is also how you fully re-provision an endpoint — but resume re-checks capacity from scratch, so the headroom a suspend released may already have been claimed by the time you resume. See [Resume an endpoint](#resume-an-endpoint).

## Authentication

Bearer token in the `Authorization` header — the same API key you use for `/v1` requests.

```http
Authorization: Bearer $OMNIVA_API_KEY
```

See [Authentication](/docs/getting-started/authentication) for how to mint and rotate keys.

A missing, malformed, revoked, or out-of-workspace key answers with a `401` or `403` whose body carries neither of the shapes below. Treat both as opaque and read the HTTP status line — see [401 Unauthorized](/docs/reference/errors#401-unauthorized).

## The Endpoint object

Every operation below that returns an endpoint returns this shape (a create response is the one exception — see [Create an endpoint](#create-an-endpoint)). `spec` and `status` never carry anything beyond what's listed here, and `status` itself is absent until the endpoint has reported one — treat every `status.*` field as optional.

`HTTP 200` `application/json`

```json
{
  "name": "chat-prod-endpoint",
  "creationTimestamp": "2026-07-28T09:12:00Z",
  "spec": {
    "models": [
      {
        "resources": {
          "gpu": 2,
          "gpuType": "nvidia/b200"
        },
        "autoscaling": {
          "minReplicas": 2,
          "maxReplicas": 8,
          "metric": "concurrency",
          "threshold": 8,
          "scaleUpWindow": 15,
          "scaleDownWindow": 900,
          "scaleToZeroWindow": 1800
        }
      }
    ],
    "annotations": {
      "oip.omniva.com/model-id": "Omniva/glm-5.3",
      "oip.omniva.com/flavor-name": "dual-gpu-standard"
    }
  },
  "status": {
    "state": "Ready",
    "conditions": [
      { "type": "Available", "status": "True", "reason": "MinimumReplicasAvailable" }
    ],
    "replicas": 2,
    "availableReplicas": 2,
    "inferenceModelId": "dedicated/chat-prod-endpoint",
    "lastUpdated": "2026-07-30T14:22:00Z"
  }
}
```

| Field | Type | Description |
|---|---|---|
| `name` | `string` | The endpoint's name. Permanent — see [Create an endpoint](#create-an-endpoint). |
| `creationTimestamp` | `string` | RFC 3339 timestamp, UTC. |
| `spec.models` | `array` | Always exactly one entry today — the model this endpoint runs. |
| `spec.models[].resources.gpu` | `integer` | GPU count for the endpoint's flavor. |
| `spec.models[].resources.gpuType` | `string` | GPU accelerator type, e.g. `nvidia/h100`, `nvidia/b200`. |
| `spec.models[].replicas` | `integer` | Present when the endpoint is statically sized. Absent when `autoscaling` is present — the two are mutually exclusive, on the wire exactly as they are on the request. |
| `spec.models[].autoscaling` | `object` | Present when the endpoint is autoscaled. See [Autoscaling](/docs/dedicated-endpoints/autoscaling) for what each field below means and how defaults are chosen. |
| `spec.models[].autoscaling.minReplicas` | `integer` | Lower bound on replicas. `0` means scale-to-zero. |
| `spec.models[].autoscaling.maxReplicas` | `integer` | Upper bound on replicas — your capacity ceiling. |
| `spec.models[].autoscaling.metric` | `string` | `concurrency` or `kv-cache-utilization`. |
| `spec.models[].autoscaling.threshold` | `number` | Per-replica setpoint for `metric`. |
| `spec.models[].autoscaling.scaleUpWindow` | `integer` | Seconds of sustained load observed before scaling up. |
| `spec.models[].autoscaling.scaleDownWindow` | `integer` | Seconds of reduced load that must hold steady before a replica is removed. |
| `spec.models[].autoscaling.scaleToZeroWindow` | `integer` | Seconds idle before the last replica is removed. |
| `spec.annotations` | `object` | Two read-only tags: `oip.omniva.com/model-id` (mirrors the endpoint's `modelId`) and `oip.omniva.com/flavor-name` (mirrors the flavor it was created with). |
| `status.state` | `string` | One of `Ready`, `Failed`, `Progressing`, or `Unknown`, computed from `status.conditions`. Read the warning below this table before you branch on it. |
| `status.conditions[].type` | `string` | Short condition name: `Available`, `Progressing`, `Degraded`, `Suspended`, `ReplicaFailure`, and `UpdateInProgress` on multi-node endpoints. Note `Failed` is a `status.state` value, never a condition type. |
| `status.conditions[].status` | `string` | `True`, `False`, or `Unknown`. Read literally — `False` means that condition is *not* currently asserted, which is often good news (e.g. a `Degraded: False` condition means the endpoint is not degraded). `Unknown` means it hasn't been determined yet, so don't read it as either. |
| `status.conditions[].reason` | `string` | Present when the condition has one. |
| `status.replicas` | `integer` | Replicas currently observed, not the target — during a change it lags or exceeds what you asked for. Absent rather than `0` when the endpoint is scaled to zero or suspended. |
| `status.availableReplicas` | `integer` | How many of those replicas are currently able to serve. Absent rather than `0` when none are. |
| `status.inferenceModelId` | `string` | The Model ID to call this endpoint with — `dedicated/<name>`. See [Call a dedicated endpoint](/docs/dedicated-endpoints/call-endpoint). Absent while the endpoint hasn't published one yet. |
| `status.lastUpdated` | `string` | RFC 3339 timestamp, UTC, of the last status write — not of the last status *change*. It advances on a steady endpoint too, so don't use it to detect that something happened. |

> **Over the HTTP API, a Failed state is not always a fault**
>
> `status.state` is computed from `status.conditions` alone: a `Ready` or `Available` condition reading `True` gives `Ready`; failing that, any condition reading `False` with a non-empty reason gives `Failed`; failing that, `Progressing` — or `Unknown` when nothing has been reported. Suspending clears `Available`, and a scale-up in progress can leave a `False` condition with a reason too, so either *can* surface as `state: Failed` with nothing broken. Read the conditions actually asserted — those whose `status` is `True`, where a `Suspended` one means stopped by request — and check `status.availableReplicas` for whether anything is serving. This is simpler than the console's own status column, which is derived separately and never shows this raw value.

## List endpoints

`GET /v1/endpoints`

Cursor-paginated. Returns every endpoint in your workspace.

| name | type | default | description |
| --- | --- | --- | --- |
| page[size] | integer | 10 | Items per page. A non-numeric, zero, or negative value is rejected with 400 — it does not fall back to the default. Values above 100 are accepted and clamped to 100, with no error and nothing in the response saying so, so ask for more than 100 and you will simply get 100. |
| page[after] | string |  | The nextCursor value from the previous response. Omit for the first page. |

Each `data[]` entry is a full [Endpoint object](#the-endpoint-object) — the same shape a `GET` of that one endpoint returns, not a summary. The example below shows a statically sized endpoint, which is the smallest complete item there is; an autoscaled one carries an `autoscaling` block in place of `replicas`, and every field is listed under [The Endpoint object](#the-endpoint-object).

`HTTP 200` `application/json`

```json
{
  "pageInfo": {
    "count": 1,
    "totalResults": 1,
    "nextCursor": ""
  },
  "data": [
    {
      "name": "pinned-endpoint",
      "creationTimestamp": "2026-07-28T09:12:00Z",
      "spec": {
        "models": [
          {
            "resources": { "gpu": 1, "gpuType": "nvidia/h100" },
            "replicas": 2
          }
        ],
        "annotations": {
          "oip.omniva.com/model-id": "Omniva/glm-5.3",
          "oip.omniva.com/flavor-name": "single-gpu-standard"
        }
      },
      "status": {
        "state": "Ready",
        "conditions": [
          { "type": "Available", "status": "True", "reason": "MinimumReplicasAvailable" }
        ],
        "replicas": 2,
        "availableReplicas": 2,
        "inferenceModelId": "dedicated/pinned-endpoint",
        "lastUpdated": "2026-07-30T14:22:00Z"
      }
    }
  ]
}
```

`nextCursor` is empty once you've read the last page.

Two shapes to code defensively against, both of them normal responses rather than errors:

- **An empty page sends `data: null`, not `[]`.** A workspace with no endpoints — or a page past the last one — answers `200` with `"count": 0` and `"data": null`. Coalesce before you iterate.
- **`status` can be absent.** A just-created endpoint hasn't reported one yet, so `endpoint["status"]` may be missing entirely; individual fields inside it (`replicas`, `inferenceModelId`) come and go the same way. Never reach through `status` without a guard.

The samples below do both.

| Status | Cause |
|---|---|
| 400 | `page[after]` isn't a valid, unexpired continue token. |
| 400 | `page[size]` isn't a positive integer. Carries `extensions.code` `INVALID_REQUEST`. |
| 500 | Unexpected server error. |

  
**Python**

```python
import requests
import os

resp = requests.get(
    "https://api.tokenfactory.omniva.com/v1/endpoints",
    headers={"Authorization": "Bearer " + os.environ["OMNIVA_API_KEY"]},
    params={"page[size]": 20},
)
resp.raise_for_status()
# data is null (not []) on an empty page, and status is absent until the
# endpoint reports one.
for endpoint in resp.json().get("data") or []:
    print(endpoint["name"], endpoint.get("status", {}).get("state", "Unknown"))
```

  
**TypeScript**

```typescript
const resp = await fetch(
  "https://api.tokenfactory.omniva.com/v1/endpoints?page[size]=20",
  { headers: { Authorization: "Bearer " + process.env.OMNIVA_API_KEY } }
);
const { data } = await resp.json();
// data is null (not []) on an empty page, and status is absent until the
// endpoint reports one.
for (const endpoint of data ?? []) {
  console.log(endpoint.name, endpoint.status?.state ?? "Unknown");
}
```

  
**cURL**

```bash
curl "https://api.tokenfactory.omniva.com/v1/endpoints?page[size]=20" \
  -H "Authorization: Bearer $OMNIVA_API_KEY"
```

## Create an endpoint

`POST /v1/endpoints`

| name | type | required | description |
| --- | --- | --- | --- |
| name | string | true | Lowercase letters, numbers, and hyphens — must start with a letter, end with a letter or number, and contain no dots — up to 40 characters. Permanent: there's no rename call. Delete and recreate to change it. Must be unique in your workspace — a name already in use returns 409. |
| modelId | string | true | The model to deploy, e.g. Omniva/glm-5.3 — an ID from the Model Library. |
| flavorName | string | true | The hardware flavor to deploy on — the same name shown for this model in the console's create flow. Scoped to modelId; flavors differ by model. |
| replicas | integer |  | Fixed replica count. Mutually exclusive with autoscaling. |
| autoscaling | object |  | Scale on load instead of running a fixed count. Mutually exclusive with replicas. maxReplicas is the only required field inside it. metric, threshold, and the three scale windows take platform defaults when omitted; minReplicas does not — see below. See Autoscaling for the full field reference. |

Send at most one of `replicas` or `autoscaling`. Sending both is rejected with a `400` whose `title` is `Validation Error` and whose `detail` is `replicas and autoscaling are mutually exclusive`; that response carries no `code`, so branch on the status. If you omit both, the selected flavor's configured scaling default is applied — either its autoscaling bounds or its fixed replica count. Which one you get depends on the flavor, so read the create response's `spec.models[0]` to see what you actually got rather than assuming a number.

That last part is where this call is more permissive than the console, which always sends exactly one of the two and rejects a request carrying neither. The default-applying behavior above is the API's alone; see [Autoscaling: `replicas` or `autoscaling` — never both](/docs/dedicated-endpoints/autoscaling#replicas-or-autoscaling-never-both).

Within a supplied `autoscaling` object, an omitted `minReplicas` is **`0`**, not `1` — the endpoint scales to zero when idle, and nothing is ready to answer a call that arrives before it has scaled back up. Send `minReplicas` explicitly if you want a warm floor; see [Autoscaling](/docs/dedicated-endpoints/autoscaling#scale-to-zero-vs-a-warm-floor) for how to choose one.

`HTTP 201` `application/json`

```json
{
  "name": "chat-prod-endpoint",
  "creationTimestamp": "2026-07-28T09:12:00Z",
  "spec": {
    "models": [
      {
        "resources": { "gpu": 2, "gpuType": "nvidia/b200" },
        "autoscaling": {
          "minReplicas": 2,
          "maxReplicas": 8,
          "metric": "concurrency",
          "threshold": 8,
          "scaleUpWindow": 15,
          "scaleDownWindow": 900,
          "scaleToZeroWindow": 1800
        }
      }
    ],
    "annotations": {
      "oip.omniva.com/model-id": "Omniva/glm-5.3",
      "oip.omniva.com/flavor-name": "dual-gpu-standard"
    }
  }
}
```

The create response has no `status` — the endpoint doesn't have one yet. Poll [Get an endpoint](#get-an-endpoint) for `status.state` once you have the name.

| Status | Cause |
|---|---|
| 400 | Missing or unrecognized field, an unknown `modelId` or `flavorName`, a model that isn't currently deployable, or both `replicas` and `autoscaling` were sent. See [Codes you can branch on](#codes-you-can-branch-on). |
| 409 | An endpoint named `name` already exists (`K8S_CONFLICT`), or [GPU_ALLOTMENT_EXCEEDED](#409-gpu-allotment-exceeded). |
| 500 | Unexpected server error. |
| 502 | The platform couldn't complete a required model or flavor lookup, so the request could not be validated. Nothing was created — retry. This body carries `detail` only, with no `code`. |
| 503 | [GPU_ALLOTMENT_UNAVAILABLE](#503-gpu-allotment-unavailable). |

  
**Python**

```python
import requests
import os

resp = requests.post(
    "https://api.tokenfactory.omniva.com/v1/endpoints",
    headers={"Authorization": "Bearer " + os.environ["OMNIVA_API_KEY"]},
    json={
        "name": "chat-prod-endpoint",
        "modelId": "Omniva/glm-5.3",
        "flavorName": "dual-gpu-standard",
        "autoscaling": {
            "minReplicas": 2,
            "maxReplicas": 8,
            "metric": "concurrency",
            "threshold": 8,
            "scaleUpWindow": 15,
            "scaleDownWindow": 900
        }
    },
)
resp.raise_for_status()
print(resp.json())
```

  
**TypeScript**

```typescript
const resp = await fetch("https://api.tokenfactory.omniva.com/v1/endpoints", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.OMNIVA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "chat-prod-endpoint",
    modelId: "Omniva/glm-5.3",
    flavorName: "dual-gpu-standard",
    autoscaling: {
      minReplicas: 2,
      maxReplicas: 8,
      metric: "concurrency",
      threshold: 8,
      scaleUpWindow: 15,
      scaleDownWindow: 900,
    },
  }),
});
const created = await resp.json();
```

  
**cURL**

```bash
curl -X POST https://api.tokenfactory.omniva.com/v1/endpoints \
  -H "Authorization: Bearer $OMNIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "chat-prod-endpoint",
    "modelId": "Omniva/glm-5.3",
    "flavorName": "dual-gpu-standard",
    "autoscaling": {
      "minReplicas": 2,
      "maxReplicas": 8,
      "metric": "concurrency",
      "threshold": 8,
      "scaleUpWindow": 15,
      "scaleDownWindow": 900
    }
  }'
```

## Get an endpoint

`GET /v1/endpoints/{name}`

| name | type | required | description |
| --- | --- | --- | --- |
| name | string | true | The endpoint's name (path parameter). |

Returns the [Endpoint object](#the-endpoint-object) in full, including `status`. Immediately after creation, `status` can be briefly absent — the same instant covered in [Create an endpoint](#create-an-endpoint) — before the platform has reported anything yet.

| Status | Cause |
|---|---|
| 404 | No endpoint named `name` in your workspace. |
| 500 | Unexpected server error. |

  
**Python**

```python
import requests
import os

resp = requests.get(
    "https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint",
    headers={"Authorization": "Bearer " + os.environ["OMNIVA_API_KEY"]},
)
resp.raise_for_status()
# status is absent until the endpoint reports one — poll until it appears.
print(resp.json().get("status", {}).get("state", "Unknown"))
```

  
**TypeScript**

```typescript
const resp = await fetch(
  "https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint",
  { headers: { Authorization: "Bearer " + process.env.OMNIVA_API_KEY } }
);
const endpoint = await resp.json();
// status is absent until the endpoint reports one — poll until it appears.
console.log(endpoint.status?.state ?? "Unknown");
```

  
**cURL**

```bash
curl https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint \
  -H "Authorization: Bearer $OMNIVA_API_KEY"
```

## Update an endpoint

`PATCH /v1/endpoints/{name}`

Rescales an existing endpoint. This is the only thing a running endpoint's configuration lets you change — its name, model, and flavor are fixed at creation; see [Lifecycle: Edit scaling](/docs/dedicated-endpoints/lifecycle#edit-scaling).

| name | type | required | description |
| --- | --- | --- | --- |
| name | string | true | The endpoint's name (path parameter). |
| replicas | integer |  | Switch to (or stay on) a fixed replica count. Mutually exclusive with autoscaling. |
| autoscaling | object |  | Switch to (or adjust) autoscaling. Mutually exclusive with replicas. Takes the same fields as on create, but with two pairing rules that apply only here — see below. See Autoscaling. |

Send one of `replicas` or `autoscaling` — rescaling is all this call does, so a body carrying neither is rejected rather than treated as a no-op: a `400` whose `title` is `Validation Error` and whose `detail` is `Nothing to update: send replicas (fixed capacity, disables autoscaling) or an autoscaling block.` This is the one scaling rule that differs from [create](#create-an-endpoint), where omitting both applies the flavor's configured scaling default instead. Sending a fixed `replicas` count to an autoscaled endpoint disables its autoscaler; sending `autoscaling` to a fixed endpoint enables one. Sending both is rejected with the same `400` / `Validation Error` / `replicas and autoscaling are mutually exclusive` response as on create.

Two pairing rules apply on update but not on create, because half a pair would silently compose a policy out of your value and a stored one you never re-sent:

- **`metric` and `threshold` ride together.** Send both or neither. One alone is a `400` with `detail` `metric and threshold must be provided together when updating autoscaling.`
- **`minReplicas` and `maxReplicas` ride together.** Send both or neither. One alone is a `400` with `detail` `minReplicas and maxReplicas must be provided together when updating autoscaling.` An explicit `minReplicas: 0` is a valid, deliberate scale-to-zero — it's an *omitted* `minReplicas` next to a supplied `maxReplicas` that gets refused, since that would rewrite a stored floor to zero by accident.

On create, `maxReplicas` is the only required field inside `autoscaling` — neither pairing rule applies there.

`HTTP 200` `application/json`

```json
{
  "name": "chat-prod-endpoint",
  "creationTimestamp": "2026-07-28T09:12:00Z",
  "spec": {
    "models": [
      {
        "resources": { "gpu": 2, "gpuType": "nvidia/b200" },
        "replicas": 1
      }
    ],
    "annotations": {
      "oip.omniva.com/model-id": "Omniva/glm-5.3",
      "oip.omniva.com/flavor-name": "dual-gpu-standard"
    }
  },
  "status": {
    "state": "Ready",
    "conditions": [{ "type": "Available", "status": "True", "reason": "MinimumReplicasAvailable" }],
    "replicas": 1,
    "availableReplicas": 1,
    "inferenceModelId": "dedicated/chat-prod-endpoint",
    "lastUpdated": "2026-07-30T14:40:00Z"
  },
  "notice": "Autoscaling disabled - this endpoint now runs 1 fixed replica."
}
```

`notice` appears when this request enabled autoscaling, disabled it in favor of a fixed count, or edited the autoscaling block of an already-autoscaled endpoint. It's absent from every other response — including a fixed-count change on an endpoint that was already fixed, and every create, get, list, and delete response.

An update is checked against your organization's GPU allotment the same way a create is — except the endpoint's own current reservation is credited back first, so shrinking (or leaving unchanged) is never blocked by capacity the endpoint already holds. See [GPU allotment](/docs/dedicated-endpoints/gpu-allotment).

| Status | Cause |
|---|---|
| 400 | Both `replicas` and `autoscaling` were sent, *neither* was, a field failed validation, a pairing rule above was broken, or the endpoint is already being deleted. |
| 404 | No endpoint named `name` in your workspace. |
| 409 | [GPU_ALLOTMENT_EXCEEDED](#409-gpu-allotment-exceeded). |
| 500 | Unexpected server error. |
| 503 | [GPU_ALLOTMENT_UNAVAILABLE](#503-gpu-allotment-unavailable). |

  
**Python**

```python
import requests
import os

resp = requests.patch(
    "https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint",
    headers={"Authorization": "Bearer " + os.environ["OMNIVA_API_KEY"]},
    json={"replicas": 1},
)
resp.raise_for_status()
print(resp.json().get("notice"))
```

  
**TypeScript**

```typescript
const resp = await fetch(
  "https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer " + process.env.OMNIVA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ replicas: 1 }),
  }
);
const updated = await resp.json();
console.log(updated.notice);
```

  
**cURL**

```bash
curl -X PATCH https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint \
  -H "Authorization: Bearer $OMNIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replicas": 1}'
```

## Delete an endpoint

`DELETE /v1/endpoints/{name}`

Accepted rather than completed: a `200` means the deletion was taken, not that the endpoint has finished shutting down. Its allotment commitment is released. Irreversible — there's no undo, and no way to recover the name's history. Create a new endpoint (with the same or a different name) to replace it.

| name | type | required | description |
| --- | --- | --- | --- |
| name | string | true | The endpoint's name (path parameter). |

`HTTP 200` `application/json`

```json
{
  "name": "chat-prod-endpoint",
  "message": "Endpoint deleted"
}
```

| Status | Cause |
|---|---|
| 404 | No endpoint named `name` in your workspace. |
| 500 | Unexpected server error. |

  
**cURL**

```bash
curl -X DELETE https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint \
  -H "Authorization: Bearer $OMNIVA_API_KEY"
```

## Suspend an endpoint

`POST /v1/endpoints/{name}/suspend`

Stops the endpoint from serving and releases its allotment commitment immediately — a suspended endpoint doesn't count toward your [GPU allotment](/docs/dedicated-endpoints/gpu-allotment) at all. Never blocked by capacity. See [Lifecycle](/docs/dedicated-endpoints/lifecycle#suspend-and-resume) for what changes while an endpoint is suspended.

| name | type | required | description |
| --- | --- | --- | --- |
| name | string | true | The endpoint's name (path parameter). |

No request body.

`HTTP 200` `application/json`

```json
{
  "status": "suspend operation triggered",
  "name": "chat-prod-endpoint"
}
```

| Status | Cause |
|---|---|
| 400 | The endpoint is already suspended. |
| 404 | No endpoint named `name` in your workspace. |
| 500 | Unexpected server error. |

  
**cURL**

```bash
curl -X POST https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint/suspend \
  -H "Authorization: Bearer $OMNIVA_API_KEY"
```

## Resume an endpoint

`POST /v1/endpoints/{name}/resume`

Puts the endpoint back and re-checks capacity from scratch — capacity a suspended endpoint used to hold may since have been claimed by something else. Accepted rather than completed: the `200` reports that the resume was triggered, not that anything is serving yet. See [Lifecycle](/docs/dedicated-endpoints/lifecycle#suspend-and-resume).

| name | type | required | description |
| --- | --- | --- | --- |
| name | string | true | The endpoint's name (path parameter). |

No request body.

`HTTP 200` `application/json`

```json
{
  "status": "resume operation triggered",
  "name": "chat-prod-endpoint"
}
```

| Status | Cause |
|---|---|
| 400 | The endpoint is already running, or it is already being deleted. |
| 404 | No endpoint named `name` in your workspace. |
| 409 | [GPU_ALLOTMENT_EXCEEDED](#409-gpu-allotment-exceeded) — the capacity this endpoint held before being suspended is no longer free. |
| 500 | Unexpected server error. |
| 503 | [GPU_ALLOTMENT_UNAVAILABLE](#503-gpu-allotment-unavailable). |

  
**cURL**

```bash
curl -X POST https://api.tokenfactory.omniva.com/v1/endpoints/chat-prod-endpoint/resume \
  -H "Authorization: Bearer $OMNIVA_API_KEY"
```

## The error envelope

Most errors on this resource use the [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) problem-detail field shape below. Two details to handle:

- **The `Content-Type` is `application/json`**, not `application/problem+json`. Don't branch on the media type.
- **Early request-validation failures return a smaller body.** A request rejected on its raw body — an unrecognized field, a missing `flavorName`, an unknown `modelId` — answers with `detail` and `code` only, and no `type`, `title`, `status`, or `instance`. Treat every field except `detail` as optional, and read the HTTP status line rather than `status`.

  
**Problem-detail shape**

```json
{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 400,
  "detail": "replicas and autoscaling are mutually exclusive",
  "instance": "/v1/endpoints"
}
```

  
**Early-validation shape**

```json
{
  "detail": "Unknown modelId",
  "code": "MODEL_NOT_FOUND"
}
```

| Field | Type | Description |
|---|---|---|
| `type` | `string` | Always `about:blank` today — read `title` and `status`, not `type`, to classify the error. |
| `title` | `string` | Short, stable summary of the error class, e.g. `Validation Error`. |
| `status` | `integer` | The same code as the HTTP status line. |
| `detail` | `string` | Human-readable specifics. The one field present on every error body. May change wording — don't match on it. |
| `instance` | `string` | The request path recorded for the error. Opaque — don't parse it or compare it against the path you called. |
| `extensions` | `object` | Carries a stable `code` on several validation and infrastructure errors — see [Codes you can branch on](#codes-you-can-branch-on). The two GPU-allotment responses below add capacity fields alongside that `code`; no other response does. |

Pivot on the HTTP status, and on `code` where one is present — never on `detail` text.

### Codes you can branch on

`code` is part of the contract and won't change once shipped. It arrives inside `extensions` on a problem-detail body and at the top level on an early-validation body:

| Code | Status | Returned by | Meaning |
|---|---|---|---|
| `FIELD_NOT_ALLOWED` | 400 | create, update | The body carried a field this surface doesn't accept. `detail` names the offending fields and the accepted set. |
| `FLAVOR_REQUIRED` | 400 | create | No flavor was named. |
| `MODEL_NOT_FOUND` | 400 | create | `modelId` doesn't match anything in the Model Library. |
| `MODEL_NOT_LIVE` | 400 | create | The model exists but isn't currently deployable. |
| `MODEL_REVISION_MISSING` | 400 | create | The platform has no pinned revision recorded for this model, so it can't be fetched reproducibly. Nothing on your side fixes it — ask your Omniva contact. |
| `MODEL_REVISION_INVALID` | 400 | create | The model's pinned revision is malformed. Same remedy as above. |
| `MODEL_WEIGHT_FORMAT_UNSUPPORTED` | 400 | create | The model's stored weight format isn't one dedicated serving accepts. |
| `INVALID_REQUEST` | 400 | create, update | The body isn't readable as JSON, or a field has the wrong type. |
| `VALIDATION_FAILED` | 400 | any operation | The request couldn't be attributed to a workspace — usually missing or malformed workspace context on the call. |
| `K8S_NOT_FOUND` | 404 | get, delete, suspend, resume | No endpoint by that name in your workspace. |
| `K8S_CONFLICT` | 409 | create | The name is already in use. |
| `K8S_FORBIDDEN` | 403 | any operation | The platform refused the operation on the underlying infrastructure. Retrying won't help — report it with the endpoint name. |
| `K8S_UNAVAILABLE` | 503 | any operation | The platform's control layer didn't respond. Transient — retry with backoff. |
| `K8S_TIMEOUT` | 504 | any operation | The control layer didn't answer in time. Transient — retry with backoff; note this is the one place a `504` carries a JSON body rather than the gateway's non-JSON timeout. |
| `K8S_ERROR` | 500 | any operation | Unclassified infrastructure failure. Retry once; if it persists, report it. |
| `GPU_ALLOTMENT_EXCEEDED` | 409 | create, update, resume | [See below](#409-gpu-allotment-exceeded). |
| `GPU_ALLOTMENT_UNAVAILABLE` | 503 | create, update, resume | [See below](#503-gpu-allotment-unavailable). |
| `INTERNAL_ERROR` | 500 | any operation | Unhandled server error. |

A `code` is still optional, even on a status that usually carries one. An update `404` has none. Neither does a `404` raised *after* the endpoint was already found — if it is deleted between a suspend or resume being accepted and that change being written, the resulting `404` is uncoded even though the same operation's first-look `404` carries `K8S_NOT_FOUND`. The `replicas`/`autoscaling` mutual-exclusion `400` carries no code either. Always keep a fallback that branches on the status alone.

And the listed status is the usual pairing rather than a promise: the code is derived from the failure independently of the handler's status on a few paths, so a conflict surfacing mid-operation can arrive as a `500` that still carries `K8S_CONFLICT`. Between the two, the code is the stable half.

### 409 GPU_ALLOTMENT_EXCEEDED

Returned by create, update, and resume — the three operations that can grow what you have committed against your organization's [GPU allotment](/docs/dedicated-endpoints/gpu-allotment). Never returned by list, get, delete, or suspend.

`HTTP 409` `application/json`

```json
{
  "type": "about:blank",
  "title": "GPU Allotment Exceeded",
  "status": 409,
  "detail": "This change would exceed the organization's GPU allotment for this GPU type.",
  "instance": "/v1/endpoints",
  "extensions": {
    "code": "GPU_ALLOTMENT_EXCEEDED",
    "gpuType": "nvidia/h100",
    "allotment": 8,
    "committed": 8,
    "projected": 12,
    "need": 4,
    "remediation": "https://docs.tokenfactory.omniva.com/dedicated-endpoints/gpu-allotment"
  }
}
```

| Field | Type | Description |
|---|---|---|
| `code` | `string` | Always `GPU_ALLOTMENT_EXCEEDED`. |
| `gpuType` | `string` | Which GPU type hit its cap, e.g. `nvidia/h100`. |
| `allotment` | `integer` | Your organization's cap for this GPU type. |
| `committed` | `integer` | Your organization's real, current commitment for this GPU type. Unchanged by this response — the request was rejected before anything changed. |
| `projected` | `integer` | What `committed` would have become had this request gone through. Hypothetical, not real. |
| `need` | `integer` | How far over the cap `projected` lands — `projected − allotment`. |
| `remediation` | `string` | A link back to [GPU allotment](/docs/dedicated-endpoints/gpu-allotment). |

Reduce the replica count or autoscaling ceiling and retry. Beyond that, recovery depends on which operation raised it: a flavor is fixed once the endpoint exists, so choosing a smaller one is a create-time move and not a fix for an update or a resume. See [GPU allotment: What a 409 means](/docs/dedicated-endpoints/gpu-allotment#what-a-409-means) for the per-operation table, and the rest of that page for the full capacity model — including why resume re-checks capacity from scratch.

### 503 GPU_ALLOTMENT_UNAVAILABLE

The capacity check itself couldn't be completed. Distinct from a `409`: nothing was measured, so there's nothing to report.

`HTTP 503` `application/json`

```json
{
  "type": "about:blank",
  "title": "GPU Allotment Check Unavailable",
  "status": 503,
  "detail": "The GPU allotment capacity check is temporarily unavailable. Please try again.",
  "instance": "/v1/endpoints",
  "extensions": {
    "code": "GPU_ALLOTMENT_UNAVAILABLE"
  }
}
```

Retry. This one carries no capacity numbers — nothing was measured, so there are none to report.

## What next

  - [Autoscaling](/docs/dedicated-endpoints/autoscaling) — Every scaling field, its defaults, and configuration examples.
  - [Lifecycle](/docs/dedicated-endpoints/lifecycle) — What suspend, resume, edit scaling, and delete do in the console.
  - [GPU allotment headroom](/docs/api-reference/gpu-allotment-headroom) — Read your organization's capacity before you create, update, or resume.
  - [Errors & status codes](/docs/reference/errors) — The full error catalog, including the OpenAI-shape envelope used on /v1.

