Services API

List Services

GET/v1/sprites/{name}/services

List all configured services and their current state.

Responses

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

Request

CLI

sprite services list

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

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

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)

services = sprite.list_services()

result = []
for svc in services:
  item = {"name": svc.name, "cmd": svc.cmd}
  if svc.state:
      item["status"] = svc.state.status
  result.append(item)

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

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/services"

Response

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

---

Get Service

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

Get details of a specific service.

Responses

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

Request

CLI

sprite services info {service_name}

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

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

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

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

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

import json
import os

from sprites import SpritesClient

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)

svc = sprite.get_service(service_name)

result = {"name": svc.name, "cmd": svc.cmd}
if svc.state:
  result["status"] = svc.state.status

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

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/services/$SERVICE_NAME"

Response

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

---

Create Service

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

Create or update a service definition.

Query Parameters

duration:optionalduration

Time to monitor logs after starting (default: `5s`)

Request Body

cmd:string

Command to execute

args:string[]

Command arguments

env:optionalRecord<string, string>

Environment variables to add to the base service environment

dir:optionalstring

Working directory for the service

needs:string[]

Service dependencies (started first)

http_port:optionalnumber?

HTTP port for proxy routing

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

CLI

sprite services create {service_name}

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)

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

import json
import os

from sprites import SpritesClient
from sprites.services import create_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 = create_service(
  sprite,
  name=service_name,
  cmd="python",
  args=["-m", "http.server", "8000"],
  http_port=8000,
)

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

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

Response

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

---

Start Service

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

Start a service. Returns streaming NDJSON with stdout/stderr.

Query Parameters

duration:optionalduration

Time to monitor logs after starting (default: `5s`)

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:

stdout

Field	Type	Description
type	string	(const: "stdout")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Server listening on port 3000\n","timestamp":1767609000000,"type":"stdout"}

stderr

Field	Type	Description
type	string	(const: "stderr")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Warning: deprecated API usage\n","timestamp":1767609000000,"type":"stderr"}

exit

Field	Type	Description
type	string	(const: "exit")
exit_code	number	Process exit code
timestamp	number	Unix milliseconds

{"exit_code":0,"timestamp":1767609000000,"type":"exit"}

error

Field	Type	Description
type	string	(const: "error")
data	string	Error message
timestamp	number	Unix milliseconds

{"data":"Failed to start service: command not found","timestamp":1767609000000,"type":"error"}

complete

Field	Type	Description
type	string	(const: "complete")
timestamp	number	Unix milliseconds

{"log_files":{"combined":"/.sprite/logs/services/webapp.log","stderr":"/.sprite/logs/services/webapp.log","stdout":"/.sprite/logs/services/webapp.log"},"timestamp":1767609000000,"type":"complete"}

started

Field	Type	Description
type	string	(const: "started")
timestamp	number	Unix milliseconds

{"timestamp":1767609000000,"type":"started"}

Request

CLI

sprite services start {service_name}

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)

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

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

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/services/$SERVICE_NAME/start"

Response

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

---

Stop Service

POST/v1/sprites/{name}/services/{service_name}/stop

Stop a running service. Returns streaming NDJSON with service stop progress.

Query Parameters

timeout:optionalduration

Timeout waiting for service to stop (default: `10s`)

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:

stopping

Field	Type	Description
type	string	(const: "stopping")
timestamp	number	Unix milliseconds

{"timestamp":1767609000000,"type":"stopping"}

stdout

Field	Type	Description
type	string	(const: "stdout")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Server listening on port 3000\n","timestamp":1767609000000,"type":"stdout"}

stderr

Field	Type	Description
type	string	(const: "stderr")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Warning: deprecated API usage\n","timestamp":1767609000000,"type":"stderr"}

error

Field	Type	Description
type	string	(const: "error")
data	string	Error message
timestamp	number	Unix milliseconds

{"data":"Failed to start service: command not found","timestamp":1767609000000,"type":"error"}

stopped

Field	Type	Description
type	string	(const: "stopped")
exit_code	number	Process exit code
timestamp	number	Unix milliseconds

{"exit_code":0,"timestamp":1767609000000,"type":"stopped"}

complete

Field	Type	Description
type	string	(const: "complete")
timestamp	number	Unix milliseconds

{"log_files":{"combined":"/.sprite/logs/services/webapp.log","stderr":"/.sprite/logs/services/webapp.log","stdout":"/.sprite/logs/services/webapp.log"},"timestamp":1767609000000,"type":"complete"}

Request

CLI

sprite services stop {service_name}

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

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.stopService(serviceName);

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

import json
import os

from sprites import SpritesClient
from sprites.services import stop_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 = stop_service(sprite, name=service_name)

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

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/services/$SERVICE_NAME/stop"

Response

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

---

Restart Service

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

Restart a service (stop if running, then start). Returns streaming NDJSON with stop and start progress.

Query Parameters

duration:optionalduration

Time to monitor logs after starting (default: `5s`)

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:

stopping

Field	Type	Description
type	string	(const: "stopping")
timestamp	number	Unix milliseconds

{"timestamp":1767609000000,"type":"stopping"}

stopped

Field	Type	Description
type	string	(const: "stopped")
exit_code	number	Process exit code
timestamp	number	Unix milliseconds

{"exit_code":0,"timestamp":1767609000000,"type":"stopped"}

stdout

Field	Type	Description
type	string	(const: "stdout")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Server listening on port 3000\n","timestamp":1767609000000,"type":"stdout"}

stderr

Field	Type	Description
type	string	(const: "stderr")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Warning: deprecated API usage\n","timestamp":1767609000000,"type":"stderr"}

exit

Field	Type	Description
type	string	(const: "exit")
exit_code	number	Process exit code
timestamp	number	Unix milliseconds

{"exit_code":0,"timestamp":1767609000000,"type":"exit"}

error

Field	Type	Description
type	string	(const: "error")
data	string	Error message
timestamp	number	Unix milliseconds

{"data":"Failed to start service: command not found","timestamp":1767609000000,"type":"error"}

complete

Field	Type	Description
type	string	(const: "complete")
timestamp	number	Unix milliseconds

{"log_files":{"combined":"/.sprite/logs/services/webapp.log","stderr":"/.sprite/logs/services/webapp.log","stdout":"/.sprite/logs/services/webapp.log"},"timestamp":1767609000000,"type":"complete"}

started

Field	Type	Description
type	string	(const: "started")
timestamp	number	Unix milliseconds

{"timestamp":1767609000000,"type":"started"}

Request

HTTP

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/services/$SERVICE_NAME/restart"

---

Get Service Logs

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

Stream logs for a service.

Query Parameters

lines:optionalnumber

Number of lines to return from log buffer (default: all)

duration:optionalduration

Time to follow new logs (default: `0`, no follow)

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:

stdout

Field	Type	Description
type	string	(const: "stdout")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Server listening on port 3000\n","timestamp":1767609000000,"type":"stdout"}

stderr

Field	Type	Description
type	string	(const: "stderr")
data	string	Log line content
timestamp	number	Unix milliseconds

{"data":"Warning: deprecated API usage\n","timestamp":1767609000000,"type":"stderr"}

exit

Field	Type	Description
type	string	(const: "exit")
exit_code	number	Process exit code
timestamp	number	Unix milliseconds

{"exit_code":0,"timestamp":1767609000000,"type":"exit"}

error

Field	Type	Description
type	string	(const: "error")
data	string	Error message
timestamp	number	Unix milliseconds

{"data":"Failed to start service: command not found","timestamp":1767609000000,"type":"error"}

complete

Field	Type	Description
type	string	(const: "complete")
timestamp	number	Unix milliseconds

{"log_files":{"combined":"/.sprite/logs/services/webapp.log","stderr":"/.sprite/logs/services/webapp.log","stdout":"/.sprite/logs/services/webapp.log"},"timestamp":1767609000000,"type":"complete"}

Request

CLI

sprite services logs {service_name}

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

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/services/$SERVICE_NAME/logs"

Response

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

---