Sprites API

https://sprites.dev/api
Admin
Sprites API is a REST and WebSocket API for provisioning and managing isolated Linux sandboxes with...
Tokens:22,628
Snippets:137
Trust Score:6.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Go Client

Source: https://sprites.dev/api

Install the Sprites Go client library using go get.

```go
go get github.com/superfly/sprites-go
```

--------------------------------

### Start a service using client libraries

Source: https://sprites.dev/api/sprites/services

Examples for starting a service and processing the resulting log stream in Go, Node.js, and Python.

```go
token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")
serviceName := os.Getenv("SERVICE_NAME")

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

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

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

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

const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;
const serviceName = process.env.SERVICE_NAME || 'my-service';

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

const stream = await sprite.startService(serviceName);

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

```python
import json
import os

from sprites import SpritesClient
from sprites.services import start_service

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

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

stream = start_service(sprite, name=service_name)

for event in stream:
    print(json.dumps({"type": event.type, "timestamp": event.timestamp}))
```

--------------------------------

### Install Node.js Client

Source: https://sprites.dev/api

Install the Sprites Node.js client library using npm.

```javascript
npm install @fly/sprites
```

--------------------------------

### Install Python Client

Source: https://sprites.dev/api

Install the Sprites Python client library using pip.

```python
pip install sprites-py
```

--------------------------------

### Start a TTY Exec Session

Source: https://sprites.dev/api/sprites/exec

Demonstrates starting a command with TTY enabled, allowing the session to persist after the client disconnects.

```python
cmd = sprite.command(
    "python", "-c",
    "import time; print('Server ready on port 8080', flush=True); time.sleep(30)"
)
cmd.tty = True  # TTY sessions are detachable
cmd.stdout = sys.stdout.buffer  # Stream output directly
cmd.timeout = 2  # Disconnect after 2 seconds (session keeps running)

try:
    cmd.run()
except Exception:
    pass  # Timeout is expected - we disconnect while session continues
```

--------------------------------

### List Sessions Response Examples

Source: https://sprites.dev/api/sprites/exec

Example JSON responses for the list sessions endpoint.

```json
[
  {
    "bytes_per_second": 125.5,
    "command": "bash",
    "created": "2026-01-05T10:30:00Z",
    "id": 1847,
    "is_active": true,
    "last_activity": "2026-01-05T10:35:00Z",
    "tty": true,
    "workdir": "/home/sprite/myproject"
  },
  {
    "bytes_per_second": 0,
    "command": "python -m http.server 8000",
    "created": "2026-01-05T09:15:00Z",
    "id": 1923,
    "is_active": false,
    "last_activity": "2026-01-05T09:20:00Z",
    "tty": false,
    "workdir": "/home/sprite/webapp"
  }
]
```

```json
[
  {
    "id": "73",
    "command": "sleep 300",
    "workdir": "/home/sprite",
    "created": "2026-04-03T03:03:08.705Z",
    "bytesPerSecond": 2420.7989348484684,
    "isActive": false,
    "tty": true,
    "lastActivity": "2026-04-03T03:03:08.712Z"
  }
]
```

--------------------------------

### Start a service via cURL

Source: https://sprites.dev/api/sprites/services

Use this command to initiate a service start request via the REST API.

```bash
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/start" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
```

--------------------------------

### Example JSON Response for Get Checkpoint (Alternative Format)

Source: https://sprites.dev/api/sprites/checkpoints

An alternative JSON structure for the get checkpoint response, potentially from a different client version or configuration.

```json
{
  "id": "v1",
  "createTime": "2026-04-03T03:01:19.000Z",
  "comment": "my-checkpoint"
}
```

--------------------------------

### Service List Response Example

Source: https://sprites.dev/api/sprites/services

Example JSON response body returned when listing services.

```json
[
  {
    "args": [
      "-D",
      "/var/lib/postgresql/data"
    ],
    "cmd": "postgres",
    "http_port": null,
    "name": "postgres",
    "needs": [],
    "state": {
      "name": "postgres",
      "pid": 1234,
      "started_at": "2026-01-05T08:00:00Z",
      "status": "running"
    }
  },
  {
    "args": [
      "-m",
      "http.server",
      "8000"
    ],
    "cmd": "python",
    "http_port": 8000,
    "name": "webapp",
    "needs": [
      "postgres"
    ],
    "state": {
      "name": "webapp",
      "pid": 1567,
      "started_at": "2026-01-05T08:01:00Z",
      "status": "running"
    }
  }
]
```

--------------------------------

### Example JSON Response for Get Checkpoint

Source: https://sprites.dev/api/sprites/checkpoints

This is an example of the JSON output when retrieving a specific sprite checkpoint.

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

--------------------------------

### Service Log Events Example

Source: https://sprites.dev/api/sprites/services

This NDJSON output shows example log events for a service, including 'started' and 'complete' events with timestamps and log file information.

```json
{"type":"started","timestamp":1775185374166}
{"type":"complete","log_files":{"combined":"/.sprite/logs/services/my-service.log","stderr":"/.sprite/logs/services/my-service.log","stdout":"/.sprite/logs/services/my-service.log"},"timestamp":1775185379158}
```

--------------------------------

### List Exec Sessions

Source: https://sprites.dev/api/sprites/exec

Examples for retrieving a list of active exec sessions.

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

```javascript
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 sessions = await sprite.listSessions();
console.log(JSON.stringify(sessions, null, 2));
```

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

sessions = sprite.list_sessions()

result = []
for s in sessions:
    item = {
        "id": s.id,
        "command": s.command,
        "is_active": s.is_active,
        "tty": s.tty,
    }
    result.append(item)

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

--------------------------------

### Service Creation Response Example

Source: https://sprites.dev/api/sprites/services

This JSON object represents a successful response when creating a service, detailing the command, arguments, and port configuration.

```json
{
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "cmd": "python",
  "http_port": 8000,
  "name": "webapp",
  "needs": [
    "postgres"
  ],
  "state": {
    "name": "webapp",
    "started_at": "2026-01-05T10:30:00Z",
    "status": "starting"
  }
}
```

--------------------------------

### Example JSON Response for List Checkpoints

Source: https://sprites.dev/api/sprites/checkpoints

This is an example of the JSON output when listing sprite checkpoints.

```json
[
  {
    "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"
  }
]
```

--------------------------------

### Retrieve Service Details in Node.js

Source: https://sprites.dev/api/sprites/services

This Node.js example shows how to get service information using the Sprites client. It relies on SPRITE_TOKEN and SPRITE_NAME environment variables, with an optional SERVICE_NAME.

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

const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;
const serviceName = process.env.SERVICE_NAME || 'my-service';

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

const service = await sprite.getService(serviceName);
console.log(JSON.stringify(service, null, 2));
```

--------------------------------

### POST /v1/sprites/{name}/services/{service_name}/start

Source: https://sprites.dev/api/sprites/services

Starts a previously created service and returns a stream of logs in NDJSON format.

```APIDOC
## POST /v1/sprites/{name}/services/{service_name}/start

### Description
Starts a service and monitors logs for a specified duration.

### Method
POST

### Endpoint
/v1/sprites/{name}/services/{service_name}/start

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service to start.

#### Query Parameters
- **duration** (string) - Optional - Time to monitor logs (default: 5s).

### Response
#### Success Response (200)
- **Content-Type** (application/x-ndjson) - Streaming log events including stdout, stderr, exit, error, complete, and started events.
```

--------------------------------

### Single Service Response Example

Source: https://sprites.dev/api/sprites/services

Example JSON response body for a single service detail request.

```json
[
  {
    "name": "my-service",
    "cmd": "python",
    "args": [
      "-m",
      "http.server",
      "8000"
    ],
    "needs": [],
    "http_port": 8000,
    "state": {
      "name": "my-service",
      "status": "running",
      "pid": 39,
      "started_at": "2026-04-03T03:02:54.166903023Z",
      "next_restart_at": "0001-01-01T00:00:00Z"
    }
  }
]
```

--------------------------------

### POST /v1/sprites/{name}/services/{service_name}/start

Source: https://sprites.dev/api/sprites/services

Starts a service on a specified sprite and returns a stream of service log events in NDJSON format.

```APIDOC
## POST /v1/sprites/{name}/services/{service_name}/start

### Description
Starts a running service. Returns streaming NDJSON with service start progress.

### Method
POST

### Endpoint
/v1/sprites/{name}/services/{service_name}/start

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service to start.

### Response
#### Success Response (200)
- **Content-Type** (string) - application/x-ndjson

#### Response Example
{"type":"started","timestamp":1775185382600}
{"type":"complete","log_files":{"combined":"/.sprite/logs/services/my-service.log"},"timestamp":1775185387601}
```

--------------------------------

### Example Service Response with State

Source: https://sprites.dev/api/sprites/services

This JSON object shows a service response including detailed state information.

```json
{
  "name": "my-service",
  "cmd": "python",
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "needs": null,
  "http_port": 8000,
  "state": {
    "name": "my-service",
    "status": "running",
    "pid": 39,
    "started_at": "2026-04-03T03:02:54.166903023Z",
    "next_restart_at": "0001-01-01T00:00:00Z"
  }
}
```

--------------------------------

### Create Checkpoint using Node.js

Source: https://sprites.dev/api/sprites/checkpoints

This Node.js example shows how to create a checkpoint. It utilizes the `@fly/sprites` client and requires the `SPRITE_TOKEN` and `SPRITE_NAME` environment variables to be set.

```javascript
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));
}
```

--------------------------------

### Get Specific Sprite Checkpoint (Node.js)

Source: https://sprites.dev/api/sprites/checkpoints

Node.js example to get a specific sprite checkpoint. It uses environment variables for authentication and sprite name, with 'v1' as the default checkpoint ID.

```javascript
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));
```

--------------------------------

### Example JSON Response for List Checkpoints (Alternative Format)

Source: https://sprites.dev/api/sprites/checkpoints

An alternative JSON structure for the list checkpoints response, potentially from a different client version or configuration.

```json
[
  {
    "id": "Current",
    "createTime": "2026-04-03T03:02:30.000Z"
  },
  {
    "id": "v2",
    "createTime": "2026-04-03T03:02:23.000Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v1",
    "createTime": "2026-04-03T03:01:19.000Z",
    "comment": "my-checkpoint"
  },
  {
    "id": "v0",
    "createTime": "2026-04-03T03:01:19.000Z"
  }
]
```

--------------------------------

### Create Service with Node.js SDK

Source: https://sprites.dev/api/sprites/services

Create a service using the Sprites Node.js SDK. This example requires setting environment variables for authentication and sprite details. It streams service events.

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

const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;
const serviceName = process.env.SERVICE_NAME || 'my-service';

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

const stream = await sprite.createService(serviceName, {
  cmd: 'python',
  args: ['-m', 'http.server', '8000'],
  http_port: 8000,
});

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

--------------------------------

### GET /v1/sprites/{name}/services

Source: https://sprites.dev/api/sprites/services

List all configured services and their current state for a specific sprite.

```APIDOC
## GET /v1/sprites/{name}/services

### Description
List all configured services and their current state.

### Method
GET

### Endpoint
/v1/sprites/{name}/services

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.

### Response
#### Success Response (200)
- **name** (string) - Service name
- **cmd** (string) - Command to execute
- **args** (string) - Command arguments
- **needs** (string) - Service dependencies
- **http_port** (number) - HTTP port for proxy routing
- **state** (object) - Current runtime state
  - **name** (string) - Service name
  - **status** (string) - stopped, starting, running, stopping, or failed
  - **pid** (number) - Process ID when running
  - **started_at** (string) - ISO 8601 timestamp
  - **error** (string) - Error message if failed

#### Response Example
[
  {
    "name": "postgres",
    "cmd": "postgres",
    "args": ["-D", "/var/lib/postgresql/data"],
    "needs": [],
    "http_port": null,
    "state": {
      "name": "postgres",
      "status": "running",
      "pid": 1234,
      "started_at": "2026-01-05T08:00:00Z"
    }
  }
]
```

--------------------------------

### Example NDJSON Response for Checkpoint Creation

Source: https://sprites.dev/api/sprites/checkpoints

This is an example of the streaming NDJSON response received when creating a checkpoint. It includes informational messages and a completion status.

```json
[
  {
    "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"
  }
]
```

--------------------------------

### NDJSON Response Example (Single Line)

Source: https://sprites.dev/api/sprites/checkpoints

An example of a single-line NDJSON response from the API, indicating the status of a sprite checkpoint restore operation.

```json
{"type":"info","data":"Restoring from checkpoint v1...","time":"2026-04-03T03:02:33.331656679Z"}
{"type":"info","data":"Container components started successfully","time":"2026-04-03T03:02:48.541935245Z"}
{"type":"complete","data":"Restore from v1 complete","time":"2026-04-03T03:02:48.541946165Z"}
```

--------------------------------

### Execute Command via POST

Source: https://sprites.dev/api/sprites/exec

Example of executing a non-TTY command using an HTTP POST request.

```bash
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/exec" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
```

--------------------------------

### Attach to Sprite Session

Source: https://sprites.dev/api/sprites/exec

Examples for attaching to a running session and reading its output stream across different programming languages.

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

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

// Find the session from exec example
sessions, _ := sprite.ListSessions(context.Background())
var targetSession *sprites.Session
for _, s := range sessions {
	if strings.Contains(s.Command, "time.sleep") || strings.Contains(s.Command, "python") {
		targetSession = s
		break
	}
}

if targetSession == nil {
	fmt.Println("No running session found")
	os.Exit(1)
}

fmt.Printf("Attaching to session %s...\n", targetSession.ID)

// Attach and read buffered output (includes data from before we connected)
cmd := sprite.AttachSession(targetSession.ID)
stdout, _ := cmd.StdoutPipe()
cmd.Start()

// Read for 2 seconds then disconnect
done := make(chan bool)
go func() {
	buf := make([]byte, 1024)
	for {
		n, err := stdout.Read(buf)
		if n > 0 {
			fmt.Print(string(buf[:n]))
		}
		if err == io.EOF {
			break
		}
	}
	done <- true
}()

select {
case <-done:
case <-time.After(2 * time.Second):
```

```typescript
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);

// Find the session from exec example (look for sleep or bash commands)
const sessions = await sprite.listSessions();
const targetSession = sessions.find(s =>
  s.command.includes('sleep') || s.command.includes('bash') || s.command.includes('python')
);

if (!targetSession) {
  console.log('No running session found');
  process.exit(1);
}

console.log(`Attaching to session ${targetSession.id}...`);

// Attach and read buffered output using spawn with sessionId
const cmd = sprite.spawn('', [], { sessionId: targetSession.id, tty: true });

cmd.on('error', () => {
  // Ignore errors (connection close, etc.)
});

cmd.stdout.on('data', (chunk: Buffer) => {
  process.stdout.write(chunk);
});

// Exit after 2 seconds
setTimeout(() => process.exit(0), 2000);
```

```python
import os
import sys

from sprites import SpritesClient

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

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

# Find the session from exec example
sessions = sprite.list_sessions()
target_session = None
for s in sessions:
    if "time.sleep" in s.command or "python" in s.command:
        target_session = s
        break

if not target_session:
    print("No running session found")
    sys.exit(1)

print(f"Attaching to session {target_session.id}...")

# Attach and read buffered output (includes data from before we connected)
cmd = sprite.attach_session(target_session.id)
cmd.stdout = sys.stdout.buffer
cmd.timeout = 2

try:
    cmd.run()
except Exception:
    pass  # Timeout is expected
```

--------------------------------

### NDJSON Log Output Example

Source: https://sprites.dev/api/sprites/services

This is an example of the NDJSON (Newline Delimited JSON) format for service logs, showing stdout and stderr entries, as well as a completion message.

```json
[
  {
    "data": "Server started\n",
    "timestamp": 1735988400000,
    "type": "stdout"
  },
  {
    "data": "Handling request from 127.0.0.1\n",
    "timestamp": 1735988450000,
    "type": "stdout"
  },
  {
    "data": "Warning: slow query detected\n",
    "timestamp": 1735988455000,
    "type": "stderr"
  },
  {
    "log_files": {
      "stdout": "/.sprite/logs/services/webapp.log"
    },
    "timestamp": 1735988460000,
    "type": "complete"
  }
]
```

```json
{"type":"complete","log_files":{"combined":"/.sprite/logs/services/my-service.log","stderr":"/.sprite/logs/services/my-service.log","stdout":"/.sprite/logs/services/my-service.log"},"timestamp":1775185381672}
```

--------------------------------

### Example Service Response

Source: https://sprites.dev/api/sprites/services

This JSON object represents a typical successful response when retrieving service details.

```json
{
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "cmd": "python",
  "http_port": 8000,
  "name": "webapp",
  "needs": [
    "postgres"
  ],
  "state": {
    "name": "webapp",
    "pid": 1567,
    "started_at": "2026-01-05T08:01:00Z",
    "status": "running"
  }
}
```

--------------------------------

### NDJSON Response Example

Source: https://sprites.dev/api/sprites/checkpoints

This is an example of the NDJSON response format received when restoring a sprite checkpoint. Each line is a valid JSON object.

```json
[
  {
    "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"
  }
]
```

--------------------------------

### Fetch Service Logs with Node.js

Source: https://sprites.dev/api/sprites/services

This Node.js example demonstrates how to use the SpritesClient to fetch service logs. It requires SPRITE_TOKEN, SPRITE_NAME, and optionally SERVICE_NAME environment variables. The code handles potential errors and logs the response.

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

const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;
const serviceName = process.env.SERVICE_NAME || 'my-service';

const client = new SpritesClient(token);

// Service logs endpoint - fetch last 100 lines
const response = await fetch(
  `${client.baseURL}/v1/sprites/${spriteName}/services/${serviceName}/logs?lines=100`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  }
);

if (!response.ok) {
  const body = await response.text();
  throw new Error(`Failed to get service logs (status ${response.status}): ${body}`);
}

const logs = await response.text();
console.log(logs);
```

--------------------------------

### Stop Service Response Example

Source: https://sprites.dev/api/sprites/services

Example of a successful NDJSON response when stopping a service, detailing stopping, stopped, and completion events.

```json
[
  {
    "timestamp": 1735988400000,
    "type": "stopping"
  },
  {
    "exit_code": 0,
    "timestamp": 1735988401000,
    "type": "stopped"
  },
  {
    "log_files": {
      "stdout": "/.sprite/logs/services/webapp.log"
    },
    "timestamp": 1735988402000,
    "type": "complete"
  }
]
```

--------------------------------

### GET /v1/sprites/{name}/services/{service_name}

Source: https://sprites.dev/api/sprites/services

Retrieve the configuration and status details of a specific service.

```APIDOC
## GET /v1/sprites/{name}/services/{service_name}

### Description
Get details of a specific service.

### Method
GET

### Endpoint
/v1/sprites/{name}/services/{service_name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service.

### Response
#### Success Response (200)
- **name** (string) - Service name
- **cmd** (string) - Command to execute
- **args** (string) - Command arguments
- **needs** (string) - Service dependencies
- **http_port** (number) - HTTP port for proxy routing
- **state** (object) - Current runtime state
  - **name** (string) - Service name
  - **status** (string) - stopped, starting, running, stopping, or failed
  - **pid** (number) - Process ID when running
  - **started_at** (string) - ISO 8601 timestamp
  - **error** (string) - Error message if failed
```

--------------------------------

### Execute Python Command in Sprite (Go)

Source: https://sprites.dev/api/sprites/exec

Start a Python command in a sprite environment using the Go SDK. TTY sessions are detachable and persist after disconnection. Reads output for 2 seconds before exiting.

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

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

// Start a command that runs for 30s (TTY sessions stay alive after disconnect)
cmd := sprite.Command("python", "-c",
	"import time; print('Server ready on port 8080', flush=True); time.sleep(30)")
cmd.SetTTY(true) // TTY sessions are detachable

stdout, _ := cmd.StdoutPipe()
cmd.Start()

// Read for 2 seconds then disconnect (session keeps running)
done := make(chan bool)
go func() {
	buf := make([]byte, 1024)
	for {
		n, err := stdout.Read(buf)
		if n > 0 {
			fmt.Print(string(buf[:n]))
		}
		if err == io.EOF {
			break
		}
	}
	done <- true
}()

select {
case <-done:
case <-time.After(2 * time.Second):
}
```

--------------------------------

### Example NDJSON response data

Source: https://sprites.dev/api/sprites/services

Sample output formats for service log streams.

```json
[
  {
    "timestamp": 1735988400000,
    "type": "started"
  },
  {
    "data": "Starting server...\n",
    "timestamp": 1735988400000,
    "type": "stdout"
  },
  {
    "data": "Listening on port 8000\n",
    "timestamp": 1735988401000,
    "type": "stdout"
  },
  {
    "log_files": {
      "stdout": "/.sprite/logs/services/webapp.log"
    },
    "timestamp": 1735988402000,
    "type": "complete"
  }
]
```

```json
{"type":"started","timestamp":1775185382600}
{"type":"complete","log_files":{"combined":"/.sprite/logs/services/my-service.log","stderr":"/.sprite/logs/services/my-service.log","stdout":"/.sprite/logs/services/my-service.log"},"timestamp":1775185387601}
```

--------------------------------

### NDJSON Response Example

Source: https://sprites.dev/api/sprites/exec

This is an example of a successful streaming NDJSON response from the API, indicating a signal was sent and the process exited.

```json
[
  {
    "message": "Signaling SIGTERM to process group 1847",
    "pid": 1847,
    "signal": "SIGTERM",
    "type": "signal"
  },
  {
    "message": "Process exited",
    "type": "exited"
  },
  {
    "exit_code": 0,
    "type": "complete"
  }
]

```

--------------------------------

### List Sprite Checkpoints (Node.js)

Source: https://sprites.dev/api/sprites/checkpoints

This Node.js example lists checkpoints for a sprite. It uses environment variables SPRITE_TOKEN and SPRITE_NAME for authentication and sprite identification.

```javascript
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));
```

--------------------------------

### Example NDJSON Response for Checkpoint Creation (Detailed)

Source: https://sprites.dev/api/sprites/checkpoints

This detailed NDJSON response shows the progress and final confirmation of a checkpoint creation, including specific details like the checkpoint ID and restore instructions.

```json
{"type":"info","data":"Creating checkpoint...","time":"2026-04-03T03:02:30.387872665Z"}
{"type":"info","data":"Checkpoint created successfully","time":"2026-04-03T03:02:30.740429728Z"}
{"type":"info","data":"\nCheckpoint Details:","time":"2026-04-03T03:02:30.745971282Z"}
{"type":"info","data":"  ID: v2","time":"2026-04-03T03:02:30.745979992Z"}
{"type":"info","data":"  Created: 2026-04-03 03:02:23","time":"2026-04-03T03:02:30.745982752Z"}
{"type":"info","data":"  Path: checkpoints/v2","time":"2026-04-03T03:02:30.745983272Z"}
{"type":"info","data":"\nTo restore this checkpoint:","time":"2026-04-03T03:02:30.745983422Z"}
{"type":"info","data":"  sprite checkpoint restore v2","time":"2026-04-03T03:02:30.745984022Z"}
{"type":"info","data":"  curl -X POST /checkpoints/v2/restore","time":"2026-04-03T03:02:30.745984772Z"}
{"type":"complete","data":"Checkpoint v2 created successfully","time":"2026-04-03T03:02:30.745985382Z"}
```

--------------------------------

### GET /v1/sprites/{name}/services/{service_name}

Source: https://sprites.dev/api/sprites/services

Retrieves the details of a specific service within a sprite.

```APIDOC
## GET /v1/sprites/{name}/services/{service_name}

### Description
Retrieves the details of a specific service within a sprite.

### Method
GET

### Endpoint
/v1/sprites/{name}/services/{service_name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service.

### Response
#### Success Response (200)
- **name** (string) - Service name
- **cmd** (string) - Command to execute
- **args** (string) - Command arguments
- **needs** (string) - Service dependencies
- **http_port** (number) - HTTP port for proxy routing
- **state** (object) - Current runtime state
  - **name** (string) - Service name
  - **status** (string) - `stopped`, `starting`, `running`, or `failed`
  - **pid** (number) - Process ID when running
  - **started_at** (string) - ISO 8601 timestamp
  - **error** (string) - Error message if failed

#### Response Example
```json
{
  "name": "webapp",
  "cmd": "python",
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "needs": [
    "postgres"
  ],
  "http_port": 8000,
  "state": {
    "name": "webapp",
    "pid": 1567,
    "started_at": "2026-01-05T08:01:00Z",
    "status": "running"
  }
}
```
```

--------------------------------

### Restart a Sprite Service

Source: https://sprites.dev/api/sprites/services

Use this endpoint to restart a sprite service. It stops the service if running and then starts it. Requires sprite name, service name, and an authorization token.

```bash
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/restart" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
```

--------------------------------

### Create or Update Service Request Body

Source: https://sprites.dev/api/sprites/services

This is an example of the JSON request body used to create or update a service definition via the PUT /v1/sprites/{name}/services/{service_name} endpoint.

```json
{
  "cmd": "string",
  "args": "string",
  "env": {},
  "dir": "string",
  "needs": "string",
  "http_port": 0
}
```

--------------------------------

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

Source: https://sprites.dev/api/sprites/checkpoints

Get details of a specific checkpoint.

```APIDOC
## GET /v1/sprites/{name}/checkpoints/{checkpoint_id}

### Description
Get details of a specific checkpoint.

### Method
GET

### Endpoint
/v1/sprites/{name}/checkpoints/{checkpoint_id}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **checkpoint_id** (string) - Required - The identifier of the checkpoint.

### Response
#### Success Response (200)
- **id** (string) - Checkpoint identifier
- **create_time** (string) - When the checkpoint was created
- **source_id** (string) - Parent checkpoint ID
- **comment** (string) - User-provided description
- **health** (string) - Health status

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

--------------------------------

### Create Service with Go SDK

Source: https://sprites.dev/api/sprites/services

This Go code snippet demonstrates how to create a new service using the Sprites SDK. It requires setting environment variables for the token and sprite name, and handles service logs.

```go
token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")
serviceName := os.Getenv("SERVICE_NAME")

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

httpPort := 8000
stream, err := sprite.CreateService(context.Background(), serviceName, &sprites.ServiceRequest{
	Cmd:      "python",
	Args:     []string{" -m", "http.server", "8000"},
	HTTPPort: &httpPort,
})
if err != nil {
	log.Fatal(err)
}

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

--------------------------------

### Initialize Sprites Client (Python)

Source: https://sprites.dev/api/sprites/exec

Set up the SpritesClient in Python using an environment variable for the API token and sprite name. This client is used to interact with sprite environments.

```python
import os
import sys

from sprites import SpritesClient

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

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

```

--------------------------------

### List Services in Go

Source: https://sprites.dev/api/sprites/services

Fetch service information using the Sprites Go client library.

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

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

services, err := sprite.ListServices(context.Background())
if err != nil {
	log.Fatal(err)
}

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

--------------------------------

### Create Checkpoint using Go

Source: https://sprites.dev/api/sprites/checkpoints

This Go code snippet demonstrates how to create a checkpoint with a comment. It requires setting the `SPRITE_TOKEN` and `SPRITE_NAME` environment variables and uses the `sprites` client library.

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

--------------------------------

### List Services via HTTP

Source: https://sprites.dev/api/sprites/services

Retrieve a list of all configured services and their current states using a cURL request.

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

--------------------------------

### PUT /v1/sprites/{name}/services/{service_name}

Source: https://sprites.dev/api/sprites/services

Creates a new service for a specific sprite with the provided command and configuration.

```APIDOC
## PUT /v1/sprites/{name}/services/{service_name}

### Description
Creates a new service for a specific sprite.

### Method
PUT

### Endpoint
/v1/sprites/{name}/services/{service_name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service to create.

#### Request Body
- **cmd** (string) - Required - The command to run.
- **args** (array) - Optional - Arguments for the command.
- **http_port** (integer) - Optional - Port for HTTP traffic.
- **needs** (array) - Optional - Dependencies for the service.

### Response
#### Success Response (200)
- **name** (string) - Service name
- **cmd** (string) - Command executed
- **args** (array) - Arguments used
- **http_port** (integer) - Port configured
- **needs** (array) - Dependencies
- **state** (object) - Current service state
```

--------------------------------

### POST /v1/sprites/{name}/services/{service_name}/restart

Source: https://sprites.dev/api/sprites/services

Restarts a specified service for a given sprite. This involves stopping the service if it's running and then starting it again. The API returns streaming NDJSON data indicating the progress of both the stop and start operations.

```APIDOC
## POST /v1/sprites/{name}/services/{service_name}/restart

### Description
Restarts a specified service for a given sprite. This involves stopping the service if it's running and then starting it again. The API returns streaming NDJSON data indicating the progress of both the stop and start operations.

### Method
POST

### Endpoint
`/v1/sprites/{name}/services/{service_name}/restart`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service to restart.

#### Query Parameters
- **duration** (duration) - Optional - Time to monitor logs after starting (default: `5s`).

### Request Example
```json
{
  "example": "curl -X POST \"https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/restart\" \n  -H \"Authorization: Bearer $SPRITES_TOKEN\""
}
```

### Response
#### Success Response (200)
- **timestamp** (integer) - Unix milliseconds
- **type** (string) - Event type (e.g., "stopping", "stopped", "started", "complete").
- **exit_code** (integer) - Process exit code (if applicable).
- **data** (string) - Log line content (for stdout/stderr events).
- **log_files** (object) - Contains paths to log files (if applicable).

#### Response Example
```json
{
  "example": "{\"type\":\"stopping\",\"timestamp\":1775185388426}\n{\"type\":\"stopped\",\"exit_code\":143,\"timestamp\":1775185388628}\n{\"type\":\"complete\",\"log_files\":{\"combined\":\"/.sprite/logs/services/my-service.log\",\"stderr\":\"/.sprite/logs/services/my-service.log\",\"stdout\":\"/.sprite/logs/services/my-service.log\"},\"timestamp\":1775185388628}"
}
```

### Response Codes
- **200** - Success - Streaming NDJSON response
- **404** - Not Found - Resource not found
- **500** - Internal Server Error
```

--------------------------------

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

Source: https://sprites.dev/api/sprites/checkpoints

Retrieve a list of all checkpoints for a specific sprite.

```APIDOC
## GET /v1/sprites/{name}/checkpoints

### Description
Retrieve a list of all checkpoints for a specific sprite.

### Method
GET

### Endpoint
/v1/sprites/{name}/checkpoints

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.

### Response
#### Success Response (200)
- **id** (string) - Checkpoint identifier
- **create_time** (string) - When the checkpoint was created
- **comment** (string) - Optional user-provided description

#### Response Example
[
  {
    "id": "v7",
    "create_time": "2026-01-05T10:30:00Z",
    "comment": "Before database migration"
  }
]
```

--------------------------------

### Create Sprite (Go)

Source: https://sprites.dev/api

Create a sprite using the Go client. Requires the SPRITE_TOKEN environment variable.

```go
client := sprites.New(os.Getenv("SPRITE_TOKEN"))
client.CreateSprite(ctx, os.Getenv("SPRITE_NAME"), nil)
```

--------------------------------

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

Source: https://sprites.dev/api/sprites/checkpoints

Retrieves a list of all checkpoints associated with a specific sprite.

```APIDOC
## GET /v1/sprites/{name}/checkpoints

### Description
List all checkpoints for the specified sprite.

### Method
GET

### Endpoint
/v1/sprites/{name}/checkpoints

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.

### Response
#### Success Response (200)
- **id** (string) - Checkpoint identifier
- **create_time** (string) - When the checkpoint was created
- **source_id** (string) - Parent checkpoint ID
- **comment** (string) - User-provided description
- **health** (string) - Health status
```

--------------------------------

### Create Service with cURL

Source: https://sprites.dev/api/sprites/services

Use this cURL command to create a new service for a sprite, specifying the command, arguments, and HTTP port. Ensure the SPRITES_TOKEN is set.

```bash
curl -X PUT \
  "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}" \
  -H "Authorization: Bearer $SPRITES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"args":["-m","http.server","8000"],"cmd":"python","http_port":8000,"needs":["postgres"]}'
```

--------------------------------

### List Services in Node.js

Source: https://sprites.dev/api/sprites/services

Retrieve service details using the @fly/sprites client package.

```javascript
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 services = await sprite.listServices();
console.log(JSON.stringify(services, null, 2));
```
Tokens:
Raw