> ## Documentation Index > Fetch the complete documentation index at: https://www.latitude.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a node pool > Adds a node pool to an LKS cluster. `mode` decides where the pool's nodes come from: - `on_demand` (default): the platform provisions `count` servers of `plan` from stock, so both fields are required. - `allocated`: the pool is built from `server_ids`, bare metal servers already in the cluster project. Each server is reinstalled with the LKS node image, which erases its disks. `plan` and `count` are rejected: the pool uses the plan the servers share, and `count` is the number of servers. Each server that fails an eligibility check is reported as its own 422 error, pointing at its index in `server_ids` and listing every reason in `meta.reasons`. `GET /lks/allocatable_servers` shows which servers can join. Allocated node pools are available only in on-demand projects: a reserved project is refused with 422 `RESERVED_PROJECT_NOT_SUPPORTED`. `kubernetes_version` defaults to the control-plane patch and may never be newer than it. `max_pods_per_node` and `mode` are set once, here — they cannot be changed later. ## OpenAPI ````yaml https://spec.speakeasy.com/latitude/latitude/latitude-sh-api-with-code-samples post /lks/clusters/{cluster_id}/nodepools openapi: 3.0.1 info: title: Latitude.sh API version: '2023-06-01' description: >- The Latitude.sh API is a RESTful API to manage your Latitude.sh account. It allows you to perform the same actions as the Latitude.sh dashboard. servers: - url: https://api.latitude.sh variables: latitude_api_key: default: - url: http://api.latitude.sh variables: latitude_api_key: default: security: [] tags: - name: API keys - name: Baselines (Preview) description: >- Preview. Available to teams with the `baselines_api` feature flag. The shape of these endpoints may change before general availability. - name: Billing - name: Elastic Ips - name: Events - name: Firewalls - name: IP Addresses - name: Managed Databases description: Managed database instances (PostgreSQL, ClickHouse) - name: Kubernetes Clusters - name: LKS - name: Marketplace apps - name: Operating Systems - name: Plans - name: Public Networks - name: Private Networks - name: Projects - name: Regions - name: Roles - name: SSH Keys - name: Servers - name: Block Storage - name: Filesystem Storage - name: Object Storage - name: Tags - name: Teams - name: Team members - name: Traffic - name: User data - name: User profile - name: VPN Sessions - name: Virtual machines - name: Virtual machine backups - name: Virtual machine restores paths: /lks/clusters/{cluster_id}/nodepools: post: tags: - LKS summary: Create a node pool description: > Adds a node pool to an LKS cluster. `mode` decides where the pool's nodes come from: - `on_demand` (default): the platform provisions `count` servers of `plan` from stock, so both fields are required. - `allocated`: the pool is built from `server_ids`, bare metal servers already in the cluster project. Each server is reinstalled with the LKS node image, which erases its disks. `plan` and `count` are rejected: the pool uses the plan the servers share, and `count` is the number of servers. Each server that fails an eligibility check is reported as its own 422 error, pointing at its index in `server_ids` and listing every reason in `meta.reasons`. `GET /lks/allocatable_servers` shows which servers can join. Allocated node pools are available only in on-demand projects: a reserved project is refused with 422 `RESERVED_PROJECT_NOT_SUPPORTED`. `kubernetes_version` defaults to the control-plane patch and may never be newer than it. `max_pods_per_node` and `mode` are set once, here — they cannot be changed later. operationId: create-lks-node-pool parameters: - name: cluster_id in: path required: true description: 'The cluster ID (format: `lksc_`).' schema: type: string requestBody: required: true content: application/json: examples: OnDemand: summary: Minimal on-demand pool value: data: type: lks_node_pools attributes: name: pool-a plan: c2-small-x86 count: 2 WithLabelsAndTaints: value: data: type: lks_node_pools attributes: name: gpu plan: g3-xlarge-x86 count: 3 max_pods_per_node: 250 labels: workload: training taints: - key: dedicated value: gpu effect: NoSchedule Allocated: summary: Allocated pool built from servers already in the project value: data: type: lks_node_pools attributes: name: gpu-owned mode: allocated server_ids: - sv_9dQKr1pRMLyd - sv_pRMLydp0dQKr1 schema: $ref: '#/components/schemas/create_lks_node_pool' application/vnd.api+json: examples: OnDemand: summary: Minimal on-demand pool value: data: type: lks_node_pools attributes: name: pool-a plan: c2-small-x86 count: 2 WithLabelsAndTaints: value: data: type: lks_node_pools attributes: name: gpu plan: g3-xlarge-x86 count: 3 max_pods_per_node: 250 labels: workload: training taints: - key: dedicated value: gpu effect: NoSchedule Allocated: summary: Allocated pool built from servers already in the project value: data: type: lks_node_pools attributes: name: gpu-owned mode: allocated server_ids: - sv_9dQKr1pRMLyd - sv_pRMLydp0dQKr1 schema: $ref: '#/components/schemas/create_lks_node_pool' responses: '201': description: Created content: application/vnd.api+json: examples: Provisioning: value: data: id: lksnp_9dQKr1pRMLyd type: lks_node_pools attributes: name: pool-a type: bare_metal mode: on_demand plan: c2-small-x86 server_ids: null description: '' count: 2 max_pods_per_node: null kubernetes_version: 1.36.3 platform_version: lks-v1.36.3-002 status: provisioning message: '' reason: WaitingForNodes ready_nodes: null labels: {} taints: [] created_at: '2026-09-01T12:05:00Z' updated_at: '2026-09-01T12:05:00Z' AllocatedProvisioning: value: data: id: lksnp_pRMLydp0dQKr1 type: lks_node_pools attributes: name: gpu-owned type: bare_metal mode: allocated plan: null server_ids: - sv_9dQKr1pRMLyd - sv_pRMLydp0dQKr1 description: '' count: 2 max_pods_per_node: null kubernetes_version: 1.36.3 platform_version: lks-v1.36.3-002 status: provisioning message: '' reason: AdoptingServers ready_nodes: null labels: {} taints: [] created_at: '2026-09-01T12:05:00Z' updated_at: '2026-09-01T12:05:00Z' schema: $ref: '#/components/schemas/lks_node_pool' '403': description: Forbidden content: application/vnd.api+json: examples: InsufficientPermissions: summary: The member role cannot perform this action value: errors: - code: USER_AUTHORIZATION_ERROR title: User Authorization Error detail: You are not authorized to perform this action. status: '403' meta: {} schema: $ref: '#/components/schemas/error_object' '404': description: Not Found content: application/vnd.api+json: examples: ClusterNotFound: summary: Unknown cluster, or a cluster owned by another team value: errors: - code: NOT_FOUND title: Cluster Not Found detail: Cluster 'lksc_pRMLydp0dQKr1' not found status: '404' meta: {} schema: $ref: '#/components/schemas/error_object' '422': description: Unprocessable Entity content: application/vnd.api+json: examples: VersionSkew: value: errors: - code: VERSION_SKEW title: Version Skew detail: >- Version skew not allowed: node pool Kubernetes 1.37.0 cannot be newer than the cluster's 1.36.3 status: '422' meta: {} MaxPodsOutOfRange: value: errors: - code: VALIDATION_ERROR title: Validation Error detail: must be between 16 and 500 status: '422' source: pointer: max_pods_per_node ReservedLabelPrefix: value: errors: - code: VALIDATION_ERROR title: Validation Error detail: >- key 'kubernetes.io/arch' uses reserved prefix 'kubernetes.io' status: '422' source: pointer: labels AllocatedServerRefused: summary: >- One error per refused server; `code` is its first reason and `meta.reasons` lists them all value: errors: - code: SERVER_LOCKED_ERROR title: Validation Error detail: Server sv_9dQKr1pRMLyd is locked status: '422' source: pointer: server_ids/0 meta: server_id: sv_9dQKr1pRMLyd reasons: - SERVER_LOCKED_ERROR attribute: server_ids/0 message: Server sv_9dQKr1pRMLyd is locked ServerPlanMismatch: value: errors: - code: SERVER_PLAN_MISMATCH title: Validation Error detail: Servers must all share one plan status: '422' source: pointer: server_ids meta: plans: - g3-large-x86 - c2-small-x86 attribute: server_ids message: Servers must all share one plan ReservedProjectNotSupported: value: errors: - code: RESERVED_PROJECT_NOT_SUPPORTED title: Reserved Project Not Supported detail: >- Allocated node pools are only available in on-demand projects status: '422' meta: {} PlanInAllocatedMode: value: errors: - code: VALIDATION_ERROR title: Validation Error detail: is derived from the servers in allocated mode status: '422' source: pointer: plan schema: $ref: '#/components/schemas/error_object' '502': description: Bad Gateway — NetBox is temporarily unavailable content: application/vnd.api+json: examples: UpstreamServiceError: value: errors: - code: UPSTREAM_SERVICE_ERROR title: Bad Gateway detail: NetBox is temporarily unavailable. Please try again. status: '502' meta: {} schema: $ref: '#/components/schemas/error_object' security: - Bearer: [] x-codeSamples: - lang: python label: Python (SDK) source: |- import latitudesh_python_sdk from latitudesh_python_sdk import Latitudesh import os with Latitudesh( bearer=os.getenv("LATITUDESH_BEARER", ""), ) as latitudesh: res = latitudesh.lks.create_lks_node_pool(cluster_id="", data={ "type": latitudesh_python_sdk.CreateLksNodePoolType.LKS_NODE_POOLS, "attributes": { "plan": "c2-small-x86", "count": 2, "name": "pool-a", }, }) # Handle response print(res) - lang: go label: Go (SDK) source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tlatitudeshgosdk \"github.com/latitudesh/latitudesh-go-sdk\"\n\t\"github.com/latitudesh/latitudesh-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := latitudeshgosdk.New(\n latitudeshgosdk.WithSecurity(os.Getenv(\"LATITUDESH_BEARER\")),\n )\n\n res, err := s.Lks.CreateLksNodePool(ctx, \"\", components.CreateLksNodePool{\n Data: components.CreateLksNodePoolData{\n Type: components.CreateLksNodePoolTypeLksNodePools,\n Attributes: components.CreateLksNodePoolAttributes{\n Plan: latitudeshgosdk.Pointer(\"c2-small-x86\"),\n Count: latitudeshgosdk.Pointer[int64](2),\n Name: latitudeshgosdk.Pointer(\"pool-a\"),\n },\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.LksNodePool != nil {\n // handle response\n }\n}" - lang: typescript label: Typescript (SDK) source: |- import { Latitudesh } from "latitudesh-typescript-sdk"; const latitudesh = new Latitudesh({ bearer: process.env["LATITUDESH_BEARER"] ?? "", }); async function run() { const result = await latitudesh.lks.createLksNodePool({ clusterId: "", createLksNodePool: { data: { type: "lks_node_pools", attributes: { plan: "c2-small-x86", count: 2, name: "pool-a", }, }, }, }); console.log(result); } run(); components: schemas: create_lks_node_pool: type: object properties: data: type: object properties: type: type: string enum: - lks_node_pools attributes: type: object properties: type: type: string enum: - bare_metal mode: type: string enum: - on_demand - allocated default: on_demand description: >- on_demand provisions new servers of `plan` from stock. allocated builds the pool from `server_ids`, servers already in the cluster project: each one is reinstalled with the LKS node image (erasing its disks) and, when it leaves the pool, reinstalled with a clean OS (no data, keys or user data are restored). plan: type: string description: >- Plan the pool nodes are provisioned from. Required in on_demand mode; rejected in allocated mode, where the plan is the one the servers already have count: type: integer minimum: 1 description: >- Number of nodes; must be >= 1. Required in on_demand mode; rejected in allocated mode, where it is the number of server_ids server_ids: type: array minItems: 1 uniqueItems: true items: type: string pattern: ^sv_[A-Za-z0-9]+$ example: sv_9dQKr1pRMLyd description: >- Required in allocated mode and rejected in on_demand mode. Servers must be bare metal, in the cluster project and location, share one plan, have been deployed with bgp_ready and not belong to another node pool. Each server that fails a check is reported as its own 422 error pointing at its index. kubernetes_version: type: string pattern: ^\d+\.\d+\.\d+$ example: 1.36.3 description: >- Patch; defaults to the cluster control-plane patch. Must not be newer than the control-plane patch (422 VERSION_SKEW) max_pods_per_node: type: integer minimum: 16 maximum: 500 example: 110 description: >- kubelet --max-pods for every node in the pool. Set once, at creation: it is immutable afterwards and a PATCH that carries it is rejected with 422. Omit to get the platform default (110). name: type: string maxLength: 100 description: Optional; generated when omitted description: type: string maxLength: 200 labels: type: object additionalProperties: type: string description: >- Kubernetes labels (max 50). Keys use Kubernetes label-key syntax; reserved prefixes (kubernetes.io, k8s.io, cluster.x-k8s.io, lks.latitude.sh and their subdomains) are rejected with 422. Values may be empty. The whole map is stored as sent. taints: type: array description: >- Kubernetes taints (max 50). Each (key, effect) pair must be unique. Key follows the same syntax and reserved-prefix rules as a label key. items: $ref: '#/components/schemas/lks_node_pool_taint' required: - type - attributes required: - data lks_node_pool: type: object properties: data: $ref: '#/components/schemas/lks_node_pool_data' error_object: type: object properties: errors: type: array items: type: object properties: code: type: string nullable: true status: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string parameter: type: string meta: type: object lks_node_pool_taint: type: object properties: key: type: string example: dedicated value: type: string nullable: true example: gpu description: >- May be empty; max 63 chars. Absent or null when the taint carries no value. effect: type: string enum: - NoSchedule - PreferNoSchedule - NoExecute example: NoSchedule required: - key - effect lks_node_pool_data: type: object properties: id: type: string example: lksnp_9dQKr1pRMLyd type: type: string enum: - lks_node_pools attributes: type: object properties: name: type: string nullable: true example: pool-a type: type: string example: bare_metal mode: type: string example: on_demand description: >- on_demand: nodes are servers provisioned from stock. allocated: nodes are servers already in the project, reinstalled to join the pool. plan: type: string nullable: true description: null for allocated node pools server_ids: type: array nullable: true items: type: string example: sv_9dQKr1pRMLyd description: >- Servers backing an allocated node pool; null for on_demand node pools description: type: string nullable: true count: type: integer nullable: true max_pods_per_node: type: integer nullable: true example: 110 description: >- null when it was not set at creation — the platform default (110) applies kubernetes_version: type: string nullable: true example: 1.36.3 platform_version: type: string nullable: true example: lks-v1.36.3-002 status: type: string nullable: true example: provisioning message: type: string nullable: true reason: type: string nullable: true example: AdoptingServers description: >- Machine-readable status reason (open enum). Allocated pools also report AdoptingServers, ServerNotEligible, ServerQuarantined, ServerReturnBlocked and ReturningServers. ready_nodes: type: integer nullable: true labels: type: object additionalProperties: type: string taints: type: array items: $ref: '#/components/schemas/lks_node_pool_taint' created_at: type: string nullable: true updated_at: type: string nullable: true securitySchemes: Bearer: type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.