Sprites API Documentation

Create Checkpoint

POST /v1/sprites/{name}/checkpoint

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

Request Body

application/json

comment string

Response

application/x-ndjson

StreamInfoEvent

type* "info"

data* String

Status message

time* DateTime

Timestamp

StreamErrorEvent

type* "error"

error* String

Error description

time* DateTime

Timestamp

StreamCompleteEvent

type* "complete"

data* String

Completion message

time* DateTime

Timestamp

Response Codes

200

Success - Streaming NDJSON response

404

Not Found - Resource not found

500

Internal Server Error

bash

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

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)

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

{"type":"info","data":"Creating checkpoint..."}
{"type":"info","data":"Checkpoint created successfully"}
{"type":"info","data":"\nCheckpoint Details:"}
{"type":"info","data":"  ID: v2"}
{"type":"info","data":"  Created: 2026-01-06 23:56:31"}
{"type":"info","data":"  Path: checkpoints/v2"}
{"type":"info","data":"\nTo restore this checkpoint:"}
{"type":"info","data":"  sprite checkpoint restore v2"}
{"type":"info","data":"  curl -X POST /checkpoints/v2/restore"}
{"type":"complete","data":"Checkpoint v2 created successfully"}

{"type":"info","data":"Creating checkpoint...","time":"2026-01-06T23:56:57.237155402Z"}
{"type":"info","data":"Checkpoint created successfully","time":"2026-01-06T23:56:57.723066395Z"}
{"type":"info","data":"\nCheckpoint Details:","time":"2026-01-06T23:56:57.723078045Z"}
{"type":"info","data":"  ID: v2","time":"2026-01-06T23:56:57.723079275Z"}
{"type":"info","data":"  Created: 2026-01-06 23:56:55","time":"2026-01-06T23:56:57.723080535Z"}
{"type":"info","data":"  Path: checkpoints/v2","time":"2026-01-06T23:56:57.723080805Z"}
{"type":"info","data":"\nTo restore this checkpoint:","time":"2026-01-06T23:56:57.723080865Z"}
{"type":"info","data":"  sprite checkpoint restore v2","time":"2026-01-06T23:56:57.723081465Z"}
{"type":"info","data":"  curl -X POST /checkpoints/v2/restore","time":"2026-01-06T23:56:57.723081915Z"}
{"type":"complete","data":"Checkpoint v2 created successfully","time":"2026-01-06T23:56:57.723082275Z"}

{"type": "info", "data": "Creating checkpoint..."}
{"type": "info", "data": "Checkpoint created successfully"}
{"type": "info", "data": "\nCheckpoint Details:"}
{"type": "info", "data": "  ID: v2"}
{"type": "info", "data": "  Created: 2026-01-07 17:27:21"}
{"type": "info", "data": "  Path: checkpoints/v2"}
{"type": "info", "data": "\nTo restore this checkpoint:"}
{"type": "info", "data": "  sprite checkpoint restore v2"}
{"type": "info", "data": "  curl -X POST /checkpoints/v2/restore"}
{"type": "complete", "data": "Checkpoint v2 created successfully"}

{"data":"Creating checkpoint...","type":"info"}
{"data":"Checkpoint created successfully","type":"info"}
{"data":"\nCheckpoint Details:","type":"info"}
{"data":"  ID: v2","type":"info"}
{"data":"  Created: 2026-01-07 00:27:49","type":"info"}
{"data":"  Path: checkpoints/v2","type":"info"}
{"data":"\nTo restore this checkpoint:","type":"info"}
{"data":"  sprite checkpoint restore v2","type":"info"}
{"data":"  curl -X POST /checkpoints/v2/restore","type":"info"}
{"data":"Checkpoint v2 created successfully","type":"complete"}

List Checkpoints

GET /v1/sprites/{name}/checkpoints

List all checkpoints.

Response

application/json

id* string

Checkpoint identifier (e.g., v7)

create_time* string

When the checkpoint was created

source_id string

Parent checkpoint ID

comment string

User-provided description

Response Codes

200

Success

404

Not Found - Resource not found

500

Internal Server Error

bash

curl -X GET \
  "https://api.sprites.dev/v1/sprites/{name}/checkpoints" \
  -H "Authorization: Bearer $SPRITES_TOKEN"

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

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

[
  {
    "id": "Current",
    "create_time": "2026-01-06T23:56:32Z"
  },
  {
    "id": "v2",
    "create_time": "2026-01-06T23:56:31Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v1",
    "create_time": "2026-01-06T23:13:45Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v0",
    "create_time": "2026-01-06T23:13:45Z"
  }
]

[
  {
    "id": "Current",
    "createTime": "2026-01-06T23:56:57.000Z"
  },
  {
    "id": "v2",
    "createTime": "2026-01-06T23:56:55.000Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v1",
    "createTime": "2026-01-06T23:12:44.000Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v0",
    "createTime": "2026-01-06T23:12:44.000Z"
  }
]

[
  {
    "id": "Current",
    "create_time": "2026-01-07T17:27:22Z"
  },
  {
    "id": "v2",
    "create_time": "2026-01-07T17:27:21Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v1",
    "create_time": "2026-01-07T14:53:34Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v0",
    "create_time": "2026-01-07T14:53:34Z"
  }
]

[
  {
    "id": "Current",
    "history": [],
    "create_time": "2026-01-07T00:27:51Z"
  },
  {
    "id": "v2",
    "history": [],
    "comment": "my-checkpoint",
    "create_time": "2026-01-07T00:27:49Z"
  },
  {
    "id": "v1",
    "history": [],
    "comment": "my-checkpoint",
    "create_time": "2026-01-06T18:58:03Z"
  },
  {
    "id": "v0",
    "history": [],
    "create_time": "2026-01-06T18:58:03Z"
  }
]

Get Checkpoint

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

Get details of a specific checkpoint.

Response

application/json

id* string

Checkpoint identifier (e.g., v7)

create_time* string

When the checkpoint was created

source_id string

Parent checkpoint ID

comment string

User-provided description

Response Codes

200

Success

404

Not Found - Resource not found

500

Internal Server Error

bash

curl -X GET \
  "https://api.sprites.dev/v1/sprites/{name}/checkpoints/{checkpoint_id}" \
  -H "Authorization: Bearer $SPRITES_TOKEN"

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

200 Response

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

{
  "id": "v1",
  "create_time": "2026-01-06T23:13:45Z",
  "comment": "my-checkpoint"
}

{
  "id": "v1",
  "createTime": "2026-01-06T23:12:44.000Z",
  "comment": "my-checkpoint"
}

{
  "id": "v1",
  "create_time": "2026-01-07T14:53:34Z",
  "comment": "my-checkpoint"
}

{
  "id": "v1",
  "history": [],
  "comment": "my-checkpoint",
  "create_time": "2026-01-06T18:58:03Z"
}

Restore Checkpoint

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

Restore to a specific checkpoint. Returns streaming NDJSON progress.

Response

application/x-ndjson

StreamInfoEvent

type* "info"

data* String

Status message

time* DateTime

Timestamp

StreamErrorEvent

type* "error"

error* String

Error description

time* DateTime

Timestamp

StreamCompleteEvent

type* "complete"

data* String

Completion message

time* DateTime

Timestamp

Response Codes

200

Success - Streaming NDJSON response

404

Not Found - Resource not found

500

Internal Server Error

bash

curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/checkpoints/{checkpoint_id}/restore" \
  -H "Authorization: Bearer $SPRITES_TOKEN"

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)

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

{"type":"info","data":"Restoring from checkpoint v1..."}
{"type":"info","data":"Container components started successfully"}
{"type":"complete","data":"Restore from v1 complete"}

{"type":"info","data":"Restoring from checkpoint v1...","time":"2026-01-06T23:57:02.96748127Z"}
{"type":"info","data":"Container components started successfully","time":"2026-01-06T23:57:04.035638904Z"}
{"type":"complete","data":"Restore from v1 complete","time":"2026-01-06T23:57:04.035645724Z"}

{"type": "info", "data": "Restoring from checkpoint v1..."}
{"type": "info", "data": "Container components started successfully"}
{"type": "complete", "data": "Restore from v1 complete"}

{"data":"Restoring from checkpoint v1...","type":"info"}
{"data":"Container components started successfully","type":"info"}
{"data":"Restore from v1 complete","type":"complete"}