Type Definitions

This page documents the data types used throughout the Sprites API.

Types

CheckpointInfo

id:string

Checkpoint identifier (e.g., `v7`)

create_time:time.Time

When the checkpoint was created

source_id:optionalstring

Parent checkpoint ID

comment:optionalstring

User-provided description

Example:

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

CreateCheckpointRequest

comment:optionalstring

Example:

{
  "comment": "Before deploying v2.0"
}

ExecKillCompleteEvent

type:string

(const: `"complete"`)

exit_code:int

Process exit code

Example:

{
  "exit_code": 0,
  "type": "complete"
}

ExecKillErrorEvent

type:string

(const: `"error"`)

message:string

Error message

Example:

{
  "message": "Warning: process may not have terminated",
  "type": "error"
}

ExecKillExitedEvent

type:string

(const: `"exited"`)

message:string

Status message

Example:

{
  "message": "Process exited",
  "type": "exited"
}

ExecKillKilledEvent

type:string

(const: `"killed"`)

message:string

Status message

Example:

{
  "message": "Process killed",
  "type": "killed"
}

ExecKillSignalEvent

type:string

(const: `"signal"`)

message:string

Status message

signal:string

Signal name (e.g., `SIGTERM`)

pid:int

Target process ID

Example:

{
  "message": "Signaling SIGTERM to process group 1847",
  "pid": 1847,
  "signal": "SIGTERM",
  "type": "signal"
}

ExecKillTimeoutEvent

type:string

(const: `"timeout"`)

message:string

Status message

Example:

{
  "message": "Timeout after 10s, sending SIGKILL",
  "type": "timeout"
}

NetworkPolicyRequest

rules:[]NetworkPolicyRule

List of network policy rules

Example:

{
  "rules": [
    {
      "action": "allow",
      "domain": "github.com"
    },
    {
      "action": "allow",
      "domain": "*.npmjs.org"
    }
  ]
}

NetworkPolicyRule

domain:optionalstring

Domain pattern (e.g., `*.github.com`)

action:optionalstring

`allow` or `deny`

include:optionalstring

Include rules from preset

Example:

{
  "action": "allow",
  "domain": "*.github.com"
}

ServiceLogCompleteEvent

type:string

(const: `"complete"`)

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogErrorEvent

type:string

(const: `"error"`)

data:string

Error message

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogExitEvent

type:string

(const: `"exit"`)

exit_code:int

Process exit code

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogStartedEvent

type:string

(const: `"started"`)

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogStderrEvent

type:string

(const: `"stderr"`)

data:string

Log line content

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogStdoutEvent

type:string

(const: `"stdout"`)

data:string

Log line content

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogStoppedEvent

type:string

(const: `"stopped"`)

exit_code:int

Process exit code

timestamp:int64

Unix milliseconds

Example:

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

ServiceLogStoppingEvent

type:string

(const: `"stopping"`)

timestamp:int64

Unix milliseconds

Example:

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

ServiceRequest

cmd:string

Command to execute

args:[]string

Command arguments

needs:[]string

Service dependencies (started first)

http_port:optional*int

HTTP port for proxy routing

Example:

{
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "cmd": "python",
  "http_port": 8000,
  "needs": [
    "postgres"
  ]
}

ServiceResponse

name:string

Service name

cmd:string

Command to execute

args:[]string

Command arguments

needs:[]string

Service dependencies

http_port:optional*int

HTTP port for proxy routing

state:optional*ServiceState

Current runtime state

Example:

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

ServiceState

name:string

Service name

status:string

`stopped`, `starting`, `running`, `stopping`, or `failed`

pid:optionalint

Process ID when running

started_at:optionalstring

ISO 8601 timestamp

error:optionalstring

Error message if failed

Example:

{
  "name": "webapp",
  "pid": 1567,
  "started_at": "2026-01-05T08:01:00Z",
  "status": "running"
}

StreamCompleteEvent

type:string

(const: `"complete"`)

data:string

Completion message

time:time.Time

Timestamp

Example:

{
  "data": "Checkpoint v3 created successfully",
  "time": "2026-01-05T10:30:00Z",
  "type": "complete"
}

StreamErrorEvent

type:string

(const: `"error"`)

error:string

Error description

time:time.Time

Timestamp

Example:

{
  "error": "Checkpoint failed: disk full",
  "time": "2026-01-05T10:30:00Z",
  "type": "error"
}

StreamInfoEvent

type:string

(const: `"info"`)

data:string

Status message

time:time.Time

Timestamp

Example:

{
  "data": "Creating checkpoint...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
}

Enums

Handler

Handler identifies a handler function

Value
ExecHandler
ExecHTTPHandler
ExecAttachHandler
ExecKillHandler
HandleCheckpoint
HandleListCheckpoints
HandleGetCheckpoint
HandleCheckpointRestore
HandleDeleteCheckpoint
HandleProxy
HandlePolicyNetwork
HandleListServices
HandleGetService
HandleCreateService
HandleStartService
HandleStopService
HandleDeleteService
HandleWebSocket
HandleSuspend
HandleLogs
MCPHandler
HandleSetSpriteEnvironment
HandleDebugCreateZombie
HandleDebugCheckProcess
HandleAdminResetState
HandleServiceLogs

Middleware

Middleware identifies a middleware function

Value
auth
wait_for_process
wait_for_storage
wait_for_policy
enrich_context

PortNotificationType

PortNotificationType represents the type of port notification

Value
port_opened
port_closed

WebSocket Messages

These message types are used for WebSocket communication in exec and proxy endpoints.

ExitMessage

type:string

(const: `"exit"`)

exit_code:int

Process exit code

Example:

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

PortNotificationMessage

type:PortNotificationType

Notification type

port:int

Port number

address:string

Proxy URL for accessing the port

pid:int

Process ID that opened/closed the port

Example:

{
  "address": "https://my-sprite.sprites.dev:3000",
  "pid": 1847,
  "port": 3000,
  "type": "port_opened"
}

ProxyInitMessage

host:string

Target hostname (typically "localhost")

port:int

Target port (1-65535)

Example:

{
  "host": "localhost",
  "port": 5432
}

ResizeMessage

type:string

(const: `"resize"`)

cols:uint16

New column count

rows:uint16

New row count

Example:

{
  "cols": 180,
  "rows": 50,
  "type": "resize"
}

SessionInfoMessage

type:string

(const: `"session_info"`)

session_id:int

Process PID

command:string

Command being executed

created:int64

Unix timestamp of session creation

cols:uint16

Terminal columns (TTY mode only)

rows:uint16

Terminal rows (TTY mode only)

is_owner:bool

Whether this attachment owns the session

tty:bool

Whether session is in TTY mode

Example:

{
  "cols": 120,
  "command": "bash",
  "created": 1767609000,
  "is_owner": true,
  "rows": 40,
  "session_id": 1847,
  "tty": true,
  "type": "session_info"
}