Checkpoints API

Create Checkpoint

POST/v1/sprites/{name}/checkpoint

Create a new checkpoint of the current sprite state. Returns streaming NDJSON progress.

Request Body

comment:optionalstring

Responses

Status	Description
`200`	Success - Streaming NDJSON response
`404`	Not Found - Resource not found
`500`	Internal Server Error

Streaming Events

This endpoint returns streaming NDJSON. Each line is one of these event types:

`info`

Field	Type	Description
`type`	`string`	(const: `"info"`)
`data`	`string`	Status message
`time`	`time.Time`	Timestamp

{"data":"Creating checkpoint...","time":"2026-01-05T10:30:00Z","type":"info"}

`error`

Field	Type	Description
`type`	`string`	(const: `"error"`)
`error`	`string`	Error description
`time`	`time.Time`	Timestamp

{"error":"Checkpoint failed: disk full","time":"2026-01-05T10:30:00Z","type":"error"}

`complete`

Field	Type	Description
`type`	`string`	(const: `"complete"`)
`data`	`string`	Completion message
`time`	`time.Time`	Timestamp

{"data":"Checkpoint v3 created successfully","time":"2026-01-05T10:30:00Z","type":"complete"}

Request

token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")

client := sprites.New(token)
sprite := client.Sprite(spriteName)

stream, err := sprite.CreateCheckpointWithComment(context.Background(), "my-checkpoint")
if err != nil {
log.Fatal(err)
}

err = stream.ProcessAll(func(msg *sprites.StreamMessage) error {
out, _ := json.Marshal(msg)
fmt.Println(string(out))
return nil
})
if err != nil {
log.Fatal(err)

// Example: Create Checkpoint
// Endpoint: POST /v1/sprites/{name}/checkpoint


const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;

const client = new SpritesClient(token);
const sprite = client.sprite(spriteName);

const stream = await sprite.createCheckpoint('my-checkpoint');

for await (const msg of stream) {
console.log(JSON.stringify(msg));
}

import json
import os

from sprites import SpritesClient

token = os.environ["SPRITE_TOKEN"]
sprite_name = os.environ["SPRITE_NAME"]

client = SpritesClient(token)
sprite = client.sprite(sprite_name)

stream = sprite.create_checkpoint("my-checkpoint")

for msg in stream:
  print(json.dumps({"type": msg.type, "data": msg.data}))

token = System.get_env("SPRITE_TOKEN")
sprite_name = System.get_env("SPRITE_NAME")

client = Sprites.new(token)
sprite = Sprites.sprite(client, sprite_name)

{:ok, messages} = Sprites.create_checkpoint(sprite, comment: "my-checkpoint")

Enum.each(messages, fn msg ->
IO.puts(Jason.encode!(Sprites.StreamMessage.to_map(msg)))
end)

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"comment":"Before deploying v2.0"}' \
"https://$SPRITE_NAME.sprites.app/v1/sprites/$SPRITE_NAME/checkpoint"

Response

[
{
  "data": "Creating checkpoint...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
},
{
  "data": "Stopping services...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
},
{
  "data": "Saving filesystem state...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
},
{
  "data": "Checkpoint v8 created",
  "time": "2026-01-05T10:30:00Z",
  "type": "complete"
}
]

List Checkpoints

GET/v1/sprites/{name}/checkpoints

List all checkpoints.

Responses

Status	Description
`200`	Success
`404`	Not Found - Resource not found
`500`	Internal Server Error

Request

token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")

client := sprites.New(token)
sprite := client.Sprite(spriteName)

checkpoints, err := sprite.ListCheckpoints(context.Background(), "")
if err != nil {
log.Fatal(err)
}

out, _ := json.MarshalIndent(checkpoints, "", "  ")
fmt.Println(string(out))

// Example: List Checkpoints
// Endpoint: GET /v1/sprites/{name}/checkpoints


const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;

const client = new SpritesClient(token);
const sprite = client.sprite(spriteName);

const checkpoints = await sprite.listCheckpoints();

console.log(JSON.stringify(checkpoints, null, 2));

import json
import os

from sprites import SpritesClient

token = os.environ["SPRITE_TOKEN"]
sprite_name = os.environ["SPRITE_NAME"]

client = SpritesClient(token)
sprite = client.sprite(sprite_name)

checkpoints = sprite.list_checkpoints()

result = []
for cp in checkpoints:
  item = {"id": cp.id, "create_time": cp.create_time.isoformat().replace("+00:00", "Z")}
  if cp.comment:
      item["comment"] = cp.comment
  result.append(item)

print(json.dumps(result, indent=2))

token = System.get_env("SPRITE_TOKEN")
sprite_name = System.get_env("SPRITE_NAME")

client = Sprites.new(token)
sprite = Sprites.sprite(client, sprite_name)

{:ok, checkpoints} = Sprites.list_checkpoints(sprite)

checkpoints
|> Enum.map(fn cp ->
cp
|> Map.from_struct()
|> Map.update(:create_time, nil, fn
  nil -> nil
  dt -> DateTime.to_iso8601(dt)
end)
|> Map.reject(fn {_k, v} -> is_nil(v) end)
end)
|> Jason.encode!(pretty: true)
|> IO.puts()

Response

[
{
  "comment": "Before database migration",
  "create_time": "2026-01-05T10:30:00Z",
  "id": "v7"
},
{
  "comment": "Stable state",
  "create_time": "2026-01-04T15:00:00Z",
  "id": "v6"
},
{
  "comment": "",
  "create_time": "2026-01-04T09:00:00Z",
  "id": "v5"
}
]

Get Checkpoint

GET/v1/sprites/{name}/checkpoints/{checkpoint_id}

Get details of a specific checkpoint.

Responses

Status	Description
`200`	Success
`404`	Not Found - Resource not found
`500`	Internal Server Error

Request

token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")
checkpointID := os.Getenv("CHECKPOINT_ID")
if checkpointID == "" {
checkpointID = "v1"
}

client := sprites.New(token)
sprite := client.Sprite(spriteName)

checkpoint, err := sprite.GetCheckpoint(context.Background(), checkpointID)
if err != nil {
log.Fatal(err)
}

out, _ := json.MarshalIndent(checkpoint, "", "  ")
fmt.Println(string(out))

// Example: Get Checkpoint
// Endpoint: GET /v1/sprites/{name}/checkpoints/{checkpoint_id}


const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;
const checkpointId = process.env.CHECKPOINT_ID || 'v1';

const client = new SpritesClient(token);
const sprite = client.sprite(spriteName);

const checkpoint = await sprite.getCheckpoint(checkpointId);

console.log(JSON.stringify(checkpoint, null, 2));

import json
import os

from sprites import SpritesClient

token = os.environ["SPRITE_TOKEN"]
sprite_name = os.environ["SPRITE_NAME"]
checkpoint_id = os.environ.get("CHECKPOINT_ID", "v1")

client = SpritesClient(token)
sprite = client.sprite(sprite_name)

checkpoint = sprite.get_checkpoint(checkpoint_id)

result = {
  "id": checkpoint.id,
  "create_time": checkpoint.create_time.isoformat().replace("+00:00", "Z"),
}
if checkpoint.comment:
  result["comment"] = checkpoint.comment

print(json.dumps(result, indent=2))

token = System.get_env("SPRITE_TOKEN")
sprite_name = System.get_env("SPRITE_NAME")
checkpoint_id = System.get_env("CHECKPOINT_ID") || "v1"

client = Sprites.new(token)
sprite = Sprites.sprite(client, sprite_name)

{:ok, checkpoint} = Sprites.get_checkpoint(sprite, checkpoint_id)

checkpoint
|> Map.from_struct()
|> Map.update(:create_time, nil, fn
nil -> nil
dt -> DateTime.to_iso8601(dt)
end)
|> Map.reject(fn {_k, v} -> is_nil(v) end)
|> Jason.encode!(pretty: true)
|> IO.puts()

Response

{
"comment": "Before database migration",
"create_time": "2026-01-05T10:30:00Z",
"id": "v7"
}

Restore Checkpoint

POST/v1/sprites/{name}/checkpoints/{checkpoint_id}/restore

Restore to a specific checkpoint. Returns streaming NDJSON progress.

Responses

Status	Description
`200`	Success - Streaming NDJSON response
`404`	Not Found - Resource not found
`500`	Internal Server Error

Streaming Events

This endpoint returns streaming NDJSON. Each line is one of these event types:

`info`

Field	Type	Description
`type`	`string`	(const: `"info"`)
`data`	`string`	Status message
`time`	`time.Time`	Timestamp

{"data":"Creating checkpoint...","time":"2026-01-05T10:30:00Z","type":"info"}

`error`

Field	Type	Description
`type`	`string`	(const: `"error"`)
`error`	`string`	Error description
`time`	`time.Time`	Timestamp

{"error":"Checkpoint failed: disk full","time":"2026-01-05T10:30:00Z","type":"error"}

`complete`

Field	Type	Description
`type`	`string`	(const: `"complete"`)
`data`	`string`	Completion message
`time`	`time.Time`	Timestamp

{"data":"Checkpoint v3 created successfully","time":"2026-01-05T10:30:00Z","type":"complete"}

Request

token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")
checkpointID := os.Getenv("CHECKPOINT_ID")
if checkpointID == "" {
checkpointID = "v1"
}

client := sprites.New(token)
sprite := client.Sprite(spriteName)

stream, err := sprite.RestoreCheckpoint(context.Background(), checkpointID)
if err != nil {
log.Fatal(err)
}

err = stream.ProcessAll(func(msg *sprites.StreamMessage) error {
out, _ := json.Marshal(msg)
fmt.Println(string(out))
return nil
})
if err != nil {
log.Fatal(err)

// Example: Restore Checkpoint
// Endpoint: POST /v1/sprites/{name}/checkpoints/{checkpoint_id}/restore


const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;
const checkpointId = process.env.CHECKPOINT_ID || 'v1';

const client = new SpritesClient(token);
const sprite = client.sprite(spriteName);

const stream = await sprite.restoreCheckpoint(checkpointId);

for await (const msg of stream) {
console.log(JSON.stringify(msg));
}

import json
import os

from sprites import SpritesClient

token = os.environ["SPRITE_TOKEN"]
sprite_name = os.environ["SPRITE_NAME"]
checkpoint_id = os.environ.get("CHECKPOINT_ID", "v1")

client = SpritesClient(token)
sprite = client.sprite(sprite_name)

stream = sprite.restore_checkpoint(checkpoint_id)

for msg in stream:
  print(json.dumps({"type": msg.type, "data": msg.data}))

token = System.get_env("SPRITE_TOKEN")
sprite_name = System.get_env("SPRITE_NAME")
checkpoint_id = System.get_env("CHECKPOINT_ID") || "v1"

client = Sprites.new(token)
sprite = Sprites.sprite(client, sprite_name)

{:ok, messages} = Sprites.restore_checkpoint(sprite, checkpoint_id)

Enum.each(messages, fn msg ->
IO.puts(Jason.encode!(Sprites.StreamMessage.to_map(msg)))
end)

Response

[
{
  "data": "Restoring to checkpoint v5...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
},
{
  "data": "Stopping services...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
},
{
  "data": "Restoring filesystem...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
},
{
  "data": "Restored to v5",
  "time": "2026-01-05T10:30:00Z",
  "type": "complete"
}
]