/v1/endpoints

Manage dedicated endpoints directly over HTTP — the same resource the console's 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.

For the concepts behind these calls — what a flavor is, how autoscaling works, what each lifecycle action does — see 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.

#Authentication

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

Authorization: Bearer $OMNIVA_API_KEY

See 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.

#The Endpoint object

Every operation below that returns an endpoint returns this shape (a create response is the one exception — see 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.

{
"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"
}
}

#List endpoints

Cursor-paginated. Returns every endpoint in your workspace.

Each data[] entry is a full 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.

{
"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.

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"))

#Create an endpoint

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.

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 for how to choose one.

{
"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 for status.state once you have the name.

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())

#Get an endpoint

Returns the Endpoint object in full, including status. Immediately after creation, status can be briefly absent — the same instant covered in Create an endpoint — before the platform has reported anything yet.

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"))

#Update an endpoint

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.

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, 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.

{
"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.

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"))

#Delete an endpoint

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": "chat-prod-endpoint",
"message": "Endpoint deleted"
}

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

#Suspend an endpoint

Stops the endpoint from serving and releases its allotment commitment immediately — a suspended endpoint doesn't count toward your GPU allotment at all. Never blocked by capacity. See Lifecycle for what changes while an endpoint is suspended.

No request body.

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

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

#Resume an endpoint

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.

No request body.

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

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 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.

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

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:

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. Never returned by list, get, delete, or suspend.

{
"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"
}
}

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 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.

{
"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