Skip to content
RuntaRunta
Start free with $50 credit

Create a checkpoint from a runtime

POST
/v2/runtimes/{runtime_id}/checkpoints
curl --request POST \
  --url https://api.runta.me/v2/runtimes/example/checkpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "full", "name": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
runtime_id
required

Runtime UUID or display name.

string

Runtime UUID or display name.

Request Bodyrequired

Section titled “Request Bodyrequired”

Checkpoint creation request.

Media typeapplication/json

Checkpoint creation request.

object
kind

Checkpoint kind. Beta supports only full.

string
default: full
Allowed values: full
name

Human-readable checkpoint name.

string
nullable

Responses

Section titled “Responses”

200

Section titled “200”

Response envelope.

Media typeapplication/json

Response envelope.

object
data
required

Checkpoint response object.

object
display_name
required

User-chosen display name.

string
id
required

Stable checkpoint UUID.

string
created_at
required

RFC3339 timestamp when the control-plane checkpoint row was created.

string
resources
required

Checkpoint resource state.

object
current
required

Current resource allocation.

object
memory_mib
required

Current memory allocation in MiB.

integer format: uint64
>= 1
observed_disk_gib
required

Worker-observed overlay virtual capacity in GiB.

integer format: uint32
limits
required

Resource limits.

object
memory_mib
required

Maximum memory in MiB.

integer format: uint64
>= 1
requests
required

Resource requests.

object
memory_mib
required

Requested baseline memory in MiB.

integer format: uint64
>= 1
vcpus
required

Requested virtual CPUs.

integer format: uint32
>= 1 <= 2147483647
disk_gib
required

Target overlay virtual capacity in GiB.

integer format: uint32
>= 16 <= 256
state
required

Checkpoint lifecycle state.

string
Allowed values: creating ready failed
source_runtime

Runtime that produced this checkpoint, or its retained name after deletion.

object
id
required

Stable runtime UUID. Null after the source runtime is deleted.

string
nullable
name
required

Runtime name captured when the checkpoint was created.

string
Example
{
  "data": {
    "state": "creating"
  }
}

401

Section titled “401”

Missing, malformed, or rejected bearer token

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

403

Section titled “403”

The bearer token is not allowed to perform this action

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

404

Section titled “404”

The requested resource was not found

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

409

Section titled “409”

The request conflicts with current resource state

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

422

Section titled “422”

Validation or application error

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

429

Section titled “429”

Rate limit exceeded

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

501

Section titled “501”

Operation is not implemented

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

503

Section titled “503”

Upstream service is unavailable

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

504

Section titled “504”

Upstream request timed out

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}

default

Section titled “default”

Error response

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: already_exists command_failed deadline_exceeded failed_precondition internal invalid_argument not_found permission_denied rate_limited unauthenticated unavailable unimplemented
message
required
string
request_id
required

UUID v7 correlation ID shared with the X-Request-Id response header.

string
Example
{
  "error": {
    "code": "already_exists"
  }
}