Create a serverless endpoint

Creates a serverless endpoint. Callers specify exactly one of gpu or cpu; neither or both returns 400. Container settings come from the body, from a serverless template referenced by templateId (body fields override the template’s), or both; image is required unless templateId is set. See CreateEndpointRequest for the full body.

The CUDA constraints live on gpu — gpu.allowedCudaVersions and gpu.minCudaVersion — so a CPU create cannot express them and the schema rejects the attempt with a 422. A non-empty set and a floor are mutually exclusive (400 if both are sent); an explicit empty set states no constraint and may accompany a floor.

Returns 201 with the created endpoint. The endpoint can accept jobs immediately, but starts with no active workers unless workers.min is greater than 0. Workers are provisioned on demand and autoscaled between workers.min and workers.max according to the scaling policy, so the first request to an idle endpoint may incur cold-start latency while a worker pulls its image and boots.

Checking what you can deploy

gpu.pools takes serverless GPU pool IDs, not the GPU type IDs used for pods. gpu.excludedTypes takes the type IDs — it subtracts specific cards from the pools you picked. Read both from the catalog before you create:

• List GPU types — the pool field carries the pool ID for each GPU type (null means that type is not in a serverless pool). Add include=AVAILABILITY&product=SERVERLESS for current serverless stock.
• List data centers — locations to constrain with dataCenterIds, with include=GPU_AVAILABILITY for stock per data center.

Unlike pod creation, you do not need to retry across GPUs yourself: list every pool you are willing to run on and workers are placed on whichever one has capacity. Listing more pools — and leaving dataCenterIds unset — gives the scheduler more room and reduces the chance of workers failing to start when a single pool is exhausted.

If your workload needs a specific card, pick the pool that holds it and exclude the rest of that pool with gpu.excludedTypes. Keep at least one type in the selection — upstream rejects a selection that leaves none.

POST /v2/serverless

cURL

serverlessEndpoint

curl --request POST \ --url https://api.runpod.io/v2/serverless \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "name": "image-generator", "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "type": "QUEUE", "gpu": { "pools": [ "ADA_24" ], "count": 1 }, "workers": { "min": 0, "max": 5, "idleTimeout": 5 }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "dataCenterIds": [ "US-KS-2" ], "timeout": 300000 } '

201

endpoint

{ "id": "4m7x2k9q", "name": "image-generator", "type": "QUEUE", "requestUrls": { "run": "https://api.runpod.ai/v2/4m7x2k9q/run", "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync", "status": "https://api.runpod.ai/v2/4m7x2k9q/status/{job_id}", "stream": "https://api.runpod.ai/v2/4m7x2k9q/stream/{job_id}", "cancel": "https://api.runpod.ai/v2/4m7x2k9q/cancel/{job_id}", "retry": "https://api.runpod.ai/v2/4m7x2k9q/retry/{job_id}", "purgeQueue": "https://api.runpod.ai/v2/4m7x2k9q/purge-queue", "health": "https://api.runpod.ai/v2/4m7x2k9q/health" }, "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404", "args": "", "disk": 20, "ports": [ "8000/http" ], "env": { "MODEL_NAME": "sdxl" }, "registry": null, "gpu": { "pools": [ "ADA_24" ], "count": 1, "allowedCudaVersions": [], "minCudaVersion": null }, "workers": { "min": 0, "max": 5, "idleTimeout": 5 }, "scaling": { "type": "QUEUE_DELAY", "queueDelay": 4 }, "dataCenterIds": [ "US-KS-2" ], "networkVolumes": [ "2q9m7x4c" ], "timeout": 300000, "flashboot": "OFF", "createdAt": "2026-06-01T12:00:00Z" }

Authorizations

Authorization · string · header · required

Runpod API key authentication. Generate an API key in the Runpod console and send it in the Authorization header as Bearer <api_key>. Keys are scoped to the permissions granted when created; requests may return 403 when a valid key lacks access to the requested resource or action.

Body

application/json

Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.

name · string · required

Minimum string length: 1

Example:

"my-inference"

scaling · object · required

Autoscaling signal — a discriminated union on type: QUEUE_DELAY (queue-based endpoints only) or REQUEST_COUNT. The scaler is chosen independently of the endpoint's routing type and can be switched on update.

Option 1

Option 2

Show child attributes

type · enum<string> · required

Request-routing model. Required — it determines the valid scaler and request URLs, so it must be chosen explicitly on every create.

Available options: QUEUE, LOAD_BALANCER

args · string

Arguments passed to the container entrypoint

Example:

""

disk · integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

env · object

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

image · string

Docker image reference

Example:

"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404"

ports · string[]

Exposed ports, formatted as port/protocol

Example:

["8888/http", "22/tcp"]

registry · string | null

Container registry credential ID (for private images)

Example:

null

gpu · object

GPU request for an endpoint create. Carries the CUDA constraints, which live here rather than at the body's top level so they are unrepresentable on a CPU endpoint.

Show child attributes

cpu · object[]

Eligible CPU configurations for each worker. Memory is derived from the selected flavor's catalog RAM multiplier. Exact duplicate configurations are rejected; the same flavor may be listed at different vCPU counts.

Minimum array length: 1

Show child attributes

dataCenterIds · string[]

Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose.

flashboot · enum<string> · default: OFF

FlashBoot cold-start acceleration mode.

• OFF — disabled
• FLASHBOOT — enabled
• PRIORITY_FLASHBOOT — enabled with priority capacity

Available options: OFF, FLASHBOOT, PRIORITY_FLASHBOOT

networkVolumes · string[]

templateId · string

ID of a serverless template to base this endpoint on. The template is resolved at create time into the same container settings you could otherwise spread into this body (image, args, disk, ports, env, registry); explicit body fields override the template's, except env, which is merged per key with body values winning. The template's allowedCudaVersions seeds gpu.allowedCudaVersions when the body omits it — but only for a GPU create, since a CPU endpoint has no gpu block to seed into, and not when the body sets gpu.minCudaVersion, since seeding a set beside a floor would manufacture the mutual-exclusion 400 from a valid request. Its pod-specific startSsh/startJupyter flags are ignored. Later template edits do not affect the endpoint. The template may be one of your own or a public catalog template — see GET /v2/catalog/templates (unknown or inaccessible ID → 404) — and must be a serverless template (→ 422).

Minimum string length: 1

Example:

"30zmvf89kd"

timeout · integer · default: 300000

workers · object

Show child attributes

Response

201

application/json

Created

Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.

id · string · required

Example:

"ep_abc123"

name · string · required

Example:

"my-inference"

workers · object · required

Show child attributes

scaling · object · required

Autoscaling signal — a discriminated union on type: QUEUE_DELAY (queue-based endpoints only) or REQUEST_COUNT. The scaler is chosen independently of the endpoint's routing type and can be switched on update.

Option 1

Option 2

Show child attributes

dataCenterIds · string[] · required

Example:

["US-TX-3"]

networkVolumes · string[] · required

Example:

["vol_abc"]

timeout · integer · required

Per-request execution timeout in milliseconds

Example:

300000

flashboot · enum<string> · required

FlashBoot cold-start acceleration mode.

• OFF — disabled
• FLASHBOOT — enabled
• PRIORITY_FLASHBOOT — enabled with priority capacity

Available options: OFF, FLASHBOOT, PRIORITY_FLASHBOOT

createdAt · string<date-time> · required

Example:

"2026-03-13T20:00:00Z"

args · string

Arguments passed to the container entrypoint

Example:

""

disk · integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

env · object

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

image · string

Docker image reference

Example:

"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404"

ports · string[]

Exposed ports, formatted as port/protocol

Example:

["8888/http", "22/tcp"]

registry · string | null

Container registry credential ID (for private images)

Example:

null

type · enum<string>

Request-routing semantics for a modern serverless endpoint.

• QUEUE — submit asynchronous or synchronous jobs through the managed queue.
• LOAD_BALANCER — send requests directly to worker-defined HTTP paths. Configure via env: PORT (server port, default 80), PORT_HEALTH (health-check port, default 80), and HEALTH_CHECK_PATH (path the load balancer polls for worker health, default /ping).

Available options: QUEUE, LOAD_BALANCER

requestUrls · object

Request URLs appropriate to the endpoint's top-level type. Queue-based endpoints provide job submission and management URLs; load-balancing endpoints provide base and health because their remaining paths are worker-defined.

Option 1

Option 2

Show child attributes

gpu · object | null

Show child attributes

cpu · object[]

Eligible CPU configurations for each worker, in the order they were submitted. Present for CPU endpoints and omitted for GPU endpoints. Memory is derived from the selected flavor's catalog RAM multiplier.

Minimum array length: 1

Show child attributes