Skip to main content
POST
/
api
/
v2
/
placements
Create placement
curl --request POST \
  --url https://reservation.nks.europe-west4.nscale.com/api/v2/placements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "training-workers",
    "description": "Host placement for a training job",
    "tags": [
      {
        "name": "workload",
        "value": "training"
      }
    ]
  },
  "spec": {
    "reservationId": "a64f9269-36e0-4312-b8d1-52d93d569b7b",
    "networkId": "61f0ad85-3001-41cb-824a-e6a047668dfe",
    "serverSpec": {
      "imageId": "ubuntu-24.04",
      "sshCertificateAuthorityId": "00de8f3c-77d6-424a-93c3-baf9153c7f21",
      "networking": {
        "securityGroups": [
          "7ddfdbf0-bdbf-4630-9220-f1e6876f2dd0"
        ]
      }
    },
    "count": 8,
    "constraints": {
      "policy": "spread",
      "maxSkew": 1,
      "minDomains": 3,
      "whenUnsatisfiable": "fail"
    }
  }
}
'
{
  "metadata": {
    "id": "b8ce034e-fccb-4d6c-a0e0-af3e3f346715",
    "name": "training-workers",
    "organizationId": "9a8c6370-4065-4d4a-9da0-7678df40cd9d",
    "projectId": "e36c058a-8eba-4f5b-91f4-f6ffb983795c",
    "creationTime": "2026-04-28T11:03:12Z",
    "createdBy": "john.doe@example.com",
    "provisioningStatus": "pending",
    "healthStatus": "healthy",
    "tags": [
      {
        "name": "workload",
        "value": "training"
      }
    ]
  },
  "spec": {
    "count": 8,
    "serverSpec": {
      "imageId": "ubuntu-24.04",
      "sshCertificateAuthorityId": "00de8f3c-77d6-424a-93c3-baf9153c7f21",
      "networking": {
        "securityGroups": [
          "7ddfdbf0-bdbf-4630-9220-f1e6876f2dd0"
        ]
      }
    },
    "constraints": {
      "policy": "spread",
      "maxSkew": 1,
      "minDomains": 3,
      "whenUnsatisfiable": "fail"
    }
  },
  "status": {
    "regionId": "c7568e2d-f9ab-453d-9a3a-51375f78426b",
    "reservationId": "a64f9269-36e0-4312-b8d1-52d93d569b7b",
    "networkId": "61f0ad85-3001-41cb-824a-e6a047668dfe",
    "readyHostCount": 0
  }
}

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

A request to create a placement.

A placement creation request.

metadata
object
required

Metadata required for all API resource reads and writes.

spec
object
required

A placement creation specification.

Response

A placement.

A placement.

metadata
object
required

Metadata required by project scoped resource reads.

spec
object
required

A placement's specification.

status
object
required

Read only status information about a placement.