---
title: "Create reservation"
method: POST
path: "/api/v2/reservations"
tags: ["Reservations"]
---

# Create reservation

`POST /api/v2/reservations`

Create a reservation.

## Request body

- ReservationV2Create — A reservation creation request.
  - `metadata` ResourceMetadata, required — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
  - `spec` ReservationV2CreateSpec, required — A reservation's specification.
    - `regionId` string, required — The region to reserve capacity in.
    - `accelerator` string, required — Public accelerator model or family to reserve.
    - `unit` string, required — Public reservation granularity to reserve.
    - `count` integer, required — Number of reservation units to reserve.
    - `organizationId` string, required — The organization to provision the reservation in.
    - `projectId` string, required — The project to provision the reservation in.

## Response `202`

A reservation.

- ReservationV2Read — A reservation.
  - `metadata` ProjectScopedResourceReadMetadata, required — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
    - `id` string, required — The unique resource ID.
    - `creationTime` string, date-time, required — The time the resource was created.
    - `createdBy` string — The user who created the resource.
    - `modifiedTime` string, date-time — The time a resource was updated.
    - `modifiedBy` string — The user who updated the resource.
    - `deletionTime` string, date-time — The time the resource was deleted.
    - `provisioningStatus` 'unknown' | 'provisioning' | 'provisioned' | 'deprovisioning' | 'error', required — The provisioning state of a resource.
    - `healthStatus` 'unknown' | 'healthy' | 'degraded' | 'error', required — The health state of a resource.
    - `organizationId` string, required — The organization identifier the resource belongs to.
    - `projectId` string, required — The project identifier the resource belongs to.
  - `spec` ReservationV2Spec, required — A reservation's specification.
    - `regionId` string, required — The region to reserve capacity in.
    - `accelerator` string, required — Public accelerator model or family to reserve.
    - `unit` string, required — Public reservation granularity to reserve.
    - `count` integer, required — Number of reservation units to reserve.
  - `status` ReservationV2Status, required — Read only status information about a reservation.
    - `machineFlavorId` string, required — Resolved Region machine flavor used for pinned servers.
    - `claimedUnitCount` integer, required — Number of reservation units successfully claimed.
    - `topologyHash` string — Hash of the claimed topology projection accepted by the reservation.
    - `topologyObservedAt` string, date-time — Time when the claimed topology projection was last observed.

## Other responses

- `400` — Request body failed schema validation, or the request does not contain all the required fields.
- `401` — Authentication failed or the access token has expired.
- `403` — Request was denied by authorization, this may be caused by the authorization token not having the required scope for an API, or the user doesn't have the necessary privileges on the provider platform.
- `404` — Unable to find a resource.
- `500` — An unexpected or unhandled error occurred. This may be a transient error and may succeed on a retry. If this isn't the case, please report it as an issue.
- `507` — Insufficient capacity to satisfy the reservation. No contiguous set of reservation units of the requested size is available in the region.

---

[API](https://skmtc.net/nscale/apis/region-service-api.md) · [All operations](https://skmtc.net/nscale/apis/region-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nscale/region-service-api/revisions/c2991b23da6e/schema)