Sprites API Documentation

Checkpoints

Create Checkpoint

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

POST /sprites/{name}/checkpoint

Request Body

application/json

comment? string

Response Body

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)

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

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-08-14 23:29:52"}
{"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..."}
{"type": "info", "data": "Checkpoint created successfully"}
{"type": "info", "data": "\nCheckpoint Details:"}
{"type": "info", "data": "  ID: v2"}
{"type": "info", "data": "  Created: 2026-08-14 23:30:33"}
{"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"}

Checkpoints

List Checkpoints

List all checkpoints.

GET /sprites/{name}/checkpoints

Response Body

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

health? string

Health status (empty = healthy, "mount_failed" = unhealthy)

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

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

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-08-14T23:29:58Z"
  },
  {
    "id": "v2",
    "create_time": "2026-08-14T23:29:52Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v1",
    "create_time": "2026-08-14T23:28:51Z",
    "comment": "my-checkpoint"
  }
]

[
  {
    "id": "Current",
    "create_time": "2026-08-14T23:30:39Z"
  },
  {
    "id": "v2",
    "create_time": "2026-08-14T23:30:33Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v1",
    "create_time": "2026-08-14T23:29:59Z",
    "comment": "my-checkpoint"
  }
]

Checkpoints

Get Checkpoint

Get details of a specific checkpoint.

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

Response Body

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

health? string

Health status (empty = healthy, "mount_failed" = unhealthy)

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

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

200 Response

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

{
  "id": "v1",
  "create_time": "2026-08-14T23:28:51Z",
  "comment": "my-checkpoint"
}

{
  "id": "v1",
  "create_time": "2026-08-14T23:29:59Z",
  "comment": "my-checkpoint"
}

Checkpoints

Restore Checkpoint

Restore to a specific checkpoint. Returns streaming NDJSON progress.

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

Response Body

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)

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

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..."}
{"type": "info", "data": "Container components started successfully"}
{"type": "complete", "data": "Restore from v1 complete"}