> ## Documentation Index > Fetch the complete documentation index at: https://runpod-b18f5ded-seo-aeo-docs-config.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a serverless endpoint > Creates a serverless endpoint. Specify `gpu` for compute (CPU serverless endpoints are read-only). 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. 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. ## OpenAPI ````yaml post /v2/serverless openapi: 3.1.0 info: title: Runpod REST API version: 2.0.0 description: Runpod public REST API — v2 servers: - url: https://api.runpod.io description: Runpod API v2 production server security: - bearerAuth: [] tags: - name: Account description: Account-scoped settings and primitives (SSH public keys). - name: Pods description: GPU and CPU pod lifecycle, configuration, actions, and log streaming. - name: Serverless description: >- Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming. - name: Templates description: Reusable pod and endpoint configuration templates. - name: Network Volumes description: Persistent network storage volumes for workloads. - name: Registries description: Container registry credentials used to pull private images. - name: Catalog description: Available GPU, CPU, data center, and public template catalog metadata. - name: Billing description: Billing history and usage cost records across resource types. paths: /v2/serverless: post: tags: - Serverless summary: Create a serverless endpoint description: | Creates a serverless endpoint. Specify `gpu` for compute (CPU serverless endpoints are read-only). 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. 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. operationId: createEndpoint requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEndpointRequest' examples: serverlessEndpoint: summary: Serverless endpoint value: name: image-generator image: runpod/pytorch:2.8.0-py3.11-cuda12.8.1 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 responses: '201': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Created content: application/json: schema: $ref: '#/components/schemas/Endpoint' examples: endpoint: summary: Successful response value: 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:2.8.0-py3.11-cuda12.8.1 args: '' disk: 20 ports: - 8000/http env: MODEL_NAME: sdxl registry: null gpu: pools: - ADA_24 count: 1 workers: min: 0 max: 5 idleTimeout: 5 scaling: type: QUEUE_DELAY queueDelay: 4 dataCenterIds: - US-KS-2 networkVolumes: - 2q9m7x4c timeout: 300000 flashboot: 'OFF' allowedCudaVersions: [] createdAt: '2026-06-01T12:00:00Z' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/UnprocessableEntityError' '429': $ref: '#/components/responses/TooManyRequestsError' default: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreateEndpointRequest: allOf: - $ref: '#/components/schemas/ContainerConfig' - if: not: required: - templateId then: required: - image - type: object required: - name - gpu - type - scaling properties: name: type: string minLength: 1 examples: - my-inference templateId: type: string minLength: 1 description: | 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 the endpoint's when the body omits it; 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). examples: - 30zmvf89kd type: allOf: - $ref: '#/components/schemas/EndpointType' description: > Request-routing model. Required — it determines the valid scaler and request URLs, so it must be chosen explicitly on every create. gpu: allOf: - $ref: '#/components/schemas/EndpointGpuConfig' unevaluatedProperties: false workers: allOf: - $ref: '#/components/schemas/EndpointWorkers' properties: min: type: integer default: 0 max: type: integer default: 3 idleTimeout: type: integer default: 10 scaling: $ref: '#/components/schemas/EndpointScaling' dataCenterIds: type: array items: type: string description: >- Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose. networkVolumes: type: array items: type: string timeout: type: integer default: 300000 flashboot: allOf: - $ref: '#/components/schemas/FlashBoot' default: 'OFF' allowedCudaVersions: type: array items: type: string pattern: ^\d+\.\d+$ description: | Acceptable CUDA versions for worker placement, as `major.minor`. Omit to accept any version (or inherit the template's constraint when creating from `templateId`). Matching is exact — discover valid values per GPU type via `GET /v2/catalog/gpus?include=AVAILABILITY` (`cudaVersions`). examples: - - '12.8' - '12.6' unevaluatedProperties: false if: required: - type properties: type: const: LOAD_BALANCER then: properties: scaling: $ref: '#/components/schemas/RequestCountScaling' Endpoint: allOf: - $ref: '#/components/schemas/ContainerConfig' - type: object required: - id - name - workers - scaling - dataCenterIds - networkVolumes - timeout - flashboot - allowedCudaVersions - createdAt properties: id: type: string examples: - ep_abc123 name: type: string examples: - my-inference type: $ref: '#/components/schemas/EndpointType' requestUrls: $ref: '#/components/schemas/EndpointRequestUrls' gpu: anyOf: - $ref: '#/components/schemas/EndpointGpuConfig' - type: 'null' cpu: description: >- Read-only. Present for CPU serverless endpoints; CPU create/update is not yet supported. anyOf: - $ref: '#/components/schemas/CpuConfig' - type: 'null' workers: allOf: - $ref: '#/components/schemas/EndpointWorkers' required: - min - max scaling: $ref: '#/components/schemas/EndpointScaling' dataCenterIds: type: array items: type: string examples: - - US-TX-3 networkVolumes: type: array items: type: string examples: - - vol_abc timeout: type: integer description: Per-request execution timeout in milliseconds examples: - 300000 flashboot: $ref: '#/components/schemas/FlashBoot' allowedCudaVersions: type: array items: type: string description: >- Acceptable CUDA versions for worker placement, as `major.minor`. Empty means any version. examples: - [] createdAt: type: string format: date-time examples: - '2026-03-13T20:00:00Z' ErrorResponse: type: object required: - title - status - detail properties: title: type: string description: Short human-readable summary examples: - Not Found status: type: integer description: HTTP status code examples: - 404 detail: type: string description: Human-readable explanation examples: - pod not found errors: type: array description: Individual request-validation failures. items: type: string examples: - - '$: additional properties ''bogus'' not allowed' ContainerConfig: description: > Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources. allOf: - $ref: '#/components/schemas/BaseContainerConfig' - type: object properties: registry: type: - string - 'null' description: Container registry credential ID (for private images) examples: - null EndpointType: type: string description: > 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`). x-enum-varnames: - EndpointTypeQueue - EndpointTypeLoadBalancer enum: - QUEUE - LOAD_BALANCER EndpointGpuConfig: type: object required: - pools properties: pools: type: array minItems: 1 description: | Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in `pool`). Workers are placed on whichever listed pool has capacity. items: type: string examples: - - ADA_24 count: type: integer minimum: 1 default: 1 description: GPUs per worker examples: - 1 EndpointWorkers: type: object additionalProperties: false properties: min: type: integer minimum: 0 description: Minimum number of workers. examples: - 0 max: type: integer minimum: 0 description: Maximum number of workers. examples: - 5 idleTimeout: type: integer minimum: 1 maximum: 3600 description: > Seconds before idle workers scale down. Not applicable to queue-based endpoints scaling on `requestCount` — rejected on create/update and omitted from responses for that combination. examples: - 5 EndpointScaling: description: | 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. oneOf: - $ref: '#/components/schemas/QueueDelayScaling' - $ref: '#/components/schemas/RequestCountScaling' discriminator: propertyName: type mapping: QUEUE_DELAY: $ref: '#/components/schemas/QueueDelayScaling' REQUEST_COUNT: $ref: '#/components/schemas/RequestCountScaling' FlashBoot: type: string description: | FlashBoot cold-start acceleration mode. - `OFF` — disabled - `FLASHBOOT` — enabled - `PRIORITY_FLASHBOOT` — enabled with priority capacity enum: - 'OFF' - FLASHBOOT - PRIORITY_FLASHBOOT RateLimitHeader: type: string description: | Live per-window quota state. Optional — omitted for rate-limit-exempt callers. A structured-field list with one member per window (`minute`, `hour`, `day`), each carrying the remaining request count `r` and seconds until the window resets `t`. Returned on responses to authenticated requests, not only on 429s. examples: - '"minute";r=0;t=12, "hour";r=2800;t=1812, "day";r=49500;t=45012' RateLimitPolicyHeader: type: string description: > Static per-window quota policy. Optional — omitted for rate-limit-exempt callers. A structured-field list with one member per window (`minute`, `hour`, `day`), each carrying the quota `q` and the window length in seconds `w`. Returned on responses to authenticated requests, not only on 429s. examples: - '"minute";q=60;w=60, "hour";q=3000;w=3600, "day";q=50000;w=86400' EndpointRequestUrls: description: | 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. oneOf: - $ref: '#/components/schemas/QueueBasedRequestUrls' - $ref: '#/components/schemas/LoadBalancingRequestUrls' CpuConfig: allOf: - $ref: '#/components/schemas/BaseCpuConfig' - type: object required: - memory properties: memory: type: integer minimum: 1 description: Memory allocated to the pod in GB. examples: - 16 BaseContainerConfig: type: object description: > Container configuration universal to every containerized resource. Compose ContainerConfig instead unless the resource cannot support private registries (clusters, until the upstream input accepts a registry credential). properties: image: type: string description: Docker image reference examples: - runpod/pytorch:2.8.0-py3.11-cuda12.8.1 args: type: string description: Arguments passed to the container entrypoint examples: - '' disk: type: integer minimum: 1 description: Container disk in GB (ephemeral, wiped on restart) examples: - 50 ports: type: array description: Exposed ports, formatted as port/protocol items: type: string examples: - - 8888/http - 22/tcp env: type: object additionalProperties: type: string description: Environment variables as key-value pairs examples: - JUPYTER_PASSWORD: hunter2 QueueDelayScaling: type: object additionalProperties: false description: Scale on queue wait time. Queue-based endpoints only. required: - type - queueDelay properties: type: type: string description: Scaler discriminator. Always `QUEUE_DELAY` for this variant. enum: - QUEUE_DELAY queueDelay: type: number format: float minimum: 0.5 description: >- Adjusts the number of workers based on how long requests wait in the queue. examples: - 4 RequestCountScaling: type: object additionalProperties: false description: | Scale on concurrent in-flight requests per worker. Required for load-balancing endpoints; also selectable for queue-based. required: - type - requestCount properties: type: type: string description: Scaler discriminator. Always `REQUEST_COUNT` for this variant. enum: - REQUEST_COUNT requestCount: type: integer minimum: 1 description: Adjusts the number of workers based on active in-flight requests. examples: - 4 QueueBasedRequestUrls: type: object additionalProperties: false required: - run - runSync - status - stream - cancel - retry - purgeQueue - health properties: run: type: string format: uri description: URL for asynchronously submitting a queued job. examples: - https://api.runpod.ai/v2/4m7x2k9q/run runSync: type: string format: uri description: >- URL for synchronously submitting a queued job. Accepts an optional `?wait=x` query parameter to control how long the request waits for job completion, defaulting to 90 seconds. examples: - https://api.runpod.ai/v2/4m7x2k9q/runsync status: type: string format: uri description: >- Check the current state, execution statistics, and results of a previously submitted job. examples: - https://api.runpod.ai/v2/4m7x2k9q/status/{job_id} stream: type: string format: uri description: >- Receive incremental results as they become available from a job that generates output progressively. examples: - https://api.runpod.ai/v2/4m7x2k9q/stream/{job_id} cancel: type: string format: uri description: Stop an in-progress job or remove a queued job before it starts. examples: - https://api.runpod.ai/v2/4m7x2k9q/cancel/{job_id} retry: type: string format: uri description: Requeue a failed or timed-out job without submitting a new request. examples: - https://api.runpod.ai/v2/4m7x2k9q/retry/{job_id} purgeQueue: type: string format: uri description: >- Remove all pending jobs from the queue. Does not affect in-progress jobs. examples: - https://api.runpod.ai/v2/4m7x2k9q/purge-queue health: type: string format: uri description: Overview of an endpoint's operational status. examples: - https://api.runpod.ai/v2/4m7x2k9q/health LoadBalancingRequestUrls: type: object additionalProperties: false required: - base - health properties: base: type: string format: uri description: Base URL for worker-defined HTTP and WebSocket paths. examples: - https://4m7x2k9q.api.runpod.ai health: type: string format: uri description: >- Health check endpoint the load balancer will periodically ping to decide if the worker is healthy enough to receive traffic. Configurable by setting the `HEALTH_CHECK_PATH` environment variable. Defaults to `/ping` if the variable is not set. examples: - https://4m7x2k9q.api.runpod.ai/ping BaseCpuConfig: type: object required: - id - vcpuCount properties: id: type: string description: CPU flavor identifier, as returned by GET /v2/catalog/cpus. examples: - cpu5c minLength: 1 vcpuCount: type: integer minimum: 2 description: >- Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two. examples: - 4 headers: RateLimit: schema: $ref: '#/components/schemas/RateLimitHeader' RateLimit-Policy: schema: $ref: '#/components/schemas/RateLimitPolicyHeader' responses: BadRequestError: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- The request could not be processed because it is malformed or conflicts with request rules. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: badRequest: summary: Bad request value: title: Bad Request status: 400 detail: request could not be processed UnauthorizedError: description: >- Authentication failed because the bearer token is missing, malformed, expired, or invalid. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingBearerToken: summary: Missing bearer token value: title: Unauthorized status: 401 detail: missing bearer token ForbiddenError: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- The bearer token is valid, but it does not grant access to the requested resource or action. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientAccess: summary: Insufficient access value: title: Forbidden status: 403 detail: access denied NotFoundError: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: The requested resource was not found or is not accessible to the caller. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Resource not found value: title: Not Found status: 404 detail: resource not found UnprocessableEntityError: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- The request body or parameters were syntactically valid but failed validation. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationFailed: summary: Validation failed value: title: Unprocessable Entity status: 422 detail: Request validation failed. TooManyRequestsError: description: > The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429. headers: Retry-After: description: Seconds to wait before retrying, per the exceeded window. schema: type: integer example: 12 RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: Rate limit exceeded value: title: Too Many Requests status: 429 detail: rate limit exceeded for the minute window securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Runpod API Key description: > Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. 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. ````