Checkpoints API

Checkpoints capture your Sprite’s complete filesystem state for instant rollback. They’re live snapshots—creation takes milliseconds with no interruption to running processes.

Use checkpoints before risky operations, to create reproducible environments, or to share known-good states across a team. Copy-on-write storage keeps incremental checkpoints small; you only store what changed.

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`	`string (ISO 8601)`	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`	`string (ISO 8601)`	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`	`string (ISO 8601)`	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)

import { SpritesClient } from '@fly/sprites';

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://api.sprites.dev/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))

import { SpritesClient } from '@fly/sprites';

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))

import { SpritesClient } from '@fly/sprites';

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`	`string (ISO 8601)`	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`	`string (ISO 8601)`	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`	`string (ISO 8601)`	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)

import { SpritesClient } from '@fly/sprites';

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"
}
]