Sprites API v1

Services

Manage background services running in your Sprite environment.

sprite-env

List Services

GET /v1/sprites/{name}/services

List all configured services and their current state.

Response

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

Get Service

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

Get details of a specific service.

Response

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

Create Service

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

Create or update a service definition.

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

needs* string

Service dependencies (started first)

http_port number

HTTP port for proxy routing

Response

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

Start Service

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

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

Query Parameters

duration duration

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

Response

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

Stop Service

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

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

Query Parameters

timeout duration

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

Response

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

Get Service Logs

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

Stream logs for a service.

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

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