Sprites API Documentation

Services

List Services

List all configured services and their current state.

GET /sprites/{name}/services

Response Body

application/json

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?

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 Codes

200

Success

404

Not Found - Resource not found

500

Internal Server Error

bash

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

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

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

[
  {
    "name": "my-service",
    "cmd": "python",
    "args": [
      "-m",
      "http.server",
      "8000"
    ],
    "needs": [],
    "http_port": 8000,
    "state": {
      "name": "my-service",
      "status": "running",
      "pid": 31,
      "started_at": "2026-08-14T23:30:20.821315738Z",
      "next_restart_at": "0001-01-01T00:00:00Z"
    }
  }
]

[
  {
    "name": "my-service",
    "cmd": "python",
    "status": "running"
  }
]

Services

Get Service

Get details of a specific service.

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

Response Body

application/json

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?

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 Codes

200

Success

404

Not Found - Resource not found

500

Internal Server Error

bash

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

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

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

{
  "name": "my-service",
  "cmd": "python",
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "needs": null,
  "http_port": 8000,
  "state": {
    "name": "my-service",
    "status": "running",
    "pid": 31,
    "started_at": "2026-08-14T23:30:20.821315738Z",
    "next_restart_at": "0001-01-01T00:00:00Z"
  }
}

{
  "name": "my-service",
  "cmd": "python",
  "status": "running"
}

Services

Create Service

Create or update a service definition.

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

Query Parameters

duration? duration

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

Request Body

application/json

cmd* string

Command to execute

args* string

Command arguments

env? map

Environment variables to add to the base service environment

dir? string

Working directory for the service

needs* string

Service dependencies (started first)

http_port? number

HTTP port for proxy routing

Response Body

application/json

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?

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 Codes

200

Success

400

Bad Request - Invalid request body

404

Not Found - Resource not found

500

Internal Server Error

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

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

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

{"type":"started","timestamp":1786750220821}
{"type":"complete","timestamp":1786750225817,"log_files":{"combined":"/.sprite/logs/services/my-service.log","stderr":"/.sprite/logs/services/my-service.log","stdout":"/.sprite/logs/services/my-service.log"}}

{"type": "started", "timestamp": 1786750259850}
{"type": "complete", "timestamp": 1786750264846}

Services

Start Service

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

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

Query Parameters

duration? duration

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

Response Body

application/x-ndjson


      ServiceLogStdoutEvent

type* "stdout"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogStderrEvent

type* "stderr"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogExitEvent

type* "exit"

exit_code* integer

Process exit code

timestamp* integer

Unix milliseconds


      ServiceLogErrorEvent

type* "error"

data* String

Error message

timestamp* integer

Unix milliseconds


      ServiceLogCompleteEvent

type* "complete"

timestamp* integer

Unix milliseconds


      ServiceLogStartedEvent

type* "started"

timestamp* integer

Unix milliseconds

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}/services/{service_name}/start" \
  -H "Authorization: Bearer $SPRITES_TOKEN"

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

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

{"type":"started","timestamp":1786750227257}
{"type":"complete","timestamp":1786750232257,"log_files":{"combined":"/.sprite/logs/services/my-service.log","stderr":"/.sprite/logs/services/my-service.log","stdout":"/.sprite/logs/services/my-service.log"}}

{"type": "started", "timestamp": 1786750265673}
{"type": "complete", "timestamp": 1786750270673}

Services

Stop Service

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

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

Query Parameters

timeout? duration

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

Response Body

application/x-ndjson


      ServiceLogStoppingEvent

type* "stopping"

timestamp* integer

Unix milliseconds


      ServiceLogStdoutEvent

type* "stdout"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogStderrEvent

type* "stderr"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogErrorEvent

type* "error"

data* String

Error message

timestamp* integer

Unix milliseconds


      ServiceLogStoppedEvent

type* "stopped"

exit_code* integer

Process exit code

timestamp* integer

Unix milliseconds


      ServiceLogCompleteEvent

type* "complete"

timestamp* integer

Unix milliseconds

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}/services/{service_name}/stop" \
  -H "Authorization: Bearer $SPRITES_TOKEN"

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

200 Response

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

{"type": "stopping", "timestamp": 1786750270955}
{"type": "stopped", "timestamp": 1786750271157}
{"type": "complete", "timestamp": 1786750271157}

Services

Restart Service

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

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

Query Parameters

duration? duration

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

Response Body

application/x-ndjson


      ServiceLogStoppingEvent

type* "stopping"

timestamp* integer

Unix milliseconds


      ServiceLogStoppedEvent

type* "stopped"

exit_code* integer

Process exit code

timestamp* integer

Unix milliseconds


      ServiceLogStdoutEvent

type* "stdout"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogStderrEvent

type* "stderr"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogExitEvent

type* "exit"

exit_code* integer

Process exit code

timestamp* integer

Unix milliseconds


      ServiceLogErrorEvent

type* "error"

data* String

Error message

timestamp* integer

Unix milliseconds


      ServiceLogCompleteEvent

type* "complete"

timestamp* integer

Unix milliseconds


      ServiceLogStartedEvent

type* "started"

timestamp* integer

Unix milliseconds

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}/services/{service_name}/restart" \
  -H "Authorization: Bearer $SPRITES_TOKEN"

200 Response

Services

Get Service Logs

Stream logs for a service.

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

Query Parameters

lines? int

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

duration? duration

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

Response Body

application/x-ndjson


      ServiceLogStdoutEvent

type* "stdout"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogStderrEvent

type* "stderr"

data* String

Log line content

timestamp* integer

Unix milliseconds


      ServiceLogExitEvent

type* "exit"

exit_code* integer

Process exit code

timestamp* integer

Unix milliseconds


      ServiceLogErrorEvent

type* "error"

data* String

Error message

timestamp* integer

Unix milliseconds


      ServiceLogCompleteEvent

type* "complete"

timestamp* integer

Unix milliseconds

Response Codes

200

Success - Streaming NDJSON response

404

Not Found - Resource not found

500

Internal Server Error

bash

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

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

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