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

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/{name}

Get details of a specific service.

Responses

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

Request

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/{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

needs:[]string

Service dependencies (started first)

http_port:optional*int

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

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://$SPRITE_NAME.sprites.app/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/{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`	`int64`	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`	`int64`	Unix milliseconds

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

`exit`

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

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

`error`

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

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

`complete`

Field	Type	Description
`type`	`string`	(const: `"complete"`)
`timestamp`	`int64`	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`	`int64`	Unix milliseconds

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

Request

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/{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`	`int64`	Unix milliseconds

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

`stdout`

Field	Type	Description
`type`	`string`	(const: `"stdout"`)
`data`	`string`	Log line content
`timestamp`	`int64`	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`	`int64`	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`	`int64`	Unix milliseconds

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

`stopped`

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

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

`complete`

Field	Type	Description
`type`	`string`	(const: `"complete"`)
`timestamp`	`int64`	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

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/{name}/logs

Stream logs for a service.

Query Parameters

lines:optionalint

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`	`int64`	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`	`int64`	Unix milliseconds

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

`exit`

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

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

`error`

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

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

`complete`

Field	Type	Description
`type`	`string`	(const: `"complete"`)
`timestamp`	`int64`	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

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