Sprites API v1

Filesystem

Read, write, and manage files within your Sprite environment.

sprite-env

Read File

GET /v1/sprites/{name}/fs/read

Read file contents from the sprite filesystem. Returns raw file bytes.

Query Parameters

path* string

Path to the file to read

workingDir* string

Working directory for resolving relative paths

Response

application/json

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}/fs/read" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
200 Response

Write File

PUT /v1/sprites/{name}/fs/write

Write file contents to the sprite filesystem. Request body contains raw file bytes.

Query Parameters

path* string

Path to the file to write

workingDir* string

Working directory for resolving relative paths

mode string

File permissions in octal (e.g., ‘0644’)

mkdir bool

Create parent directories if they don’t exist

Response

application/json
path* string
size* number
mode* string

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}/fs/write" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
200 Response 
{
  "size": 1,
  "mode": "example",
  "path": "example"
}

List Directory

GET /v1/sprites/{name}/fs/list

List directory contents.

Query Parameters

path* string

Path to the directory to list

workingDir* string

Working directory for resolving relative paths

Response

application/json
path* string
entries* Entry[]
count* number

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}/fs/list" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
200 Response 
{
  "count": 1,
  "path": "example",
  "entries": []
}

Delete File or Directory

DELETE /v1/sprites/{name}/fs/delete

Delete a file or directory.

Response

application/json
deleted* string
count* number

Response Codes

200

Success
400

Bad Request - Invalid request body
404

Not Found - Resource not found
500

Internal Server Error
bash 
curl -X DELETE \
  "https://api.sprites.dev/v1/sprites/{name}/fs/delete" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
200 Response 
{
  "count": 1,
  "deleted": "example"
}

Rename File or Directory

POST /v1/sprites/{name}/fs/rename

Rename or move a file or directory.

Request Body

application/json
source* string
dest* string
workingDir* string
asRoot* boolean

Response

application/json
source* string
dest* string

Response Codes

200

Success
400

Bad Request - Invalid request body
404

Not Found - Resource not found
500

Internal Server Error
bash 
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/fs/rename" \
  -H "Authorization: Bearer $SPRITES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asRoot":false,"dest":"example","source":"example","workingDir":"example"}'
200 Response 
{
  "source": "example",
  "dest": "example"
}

Copy File or Directory

POST /v1/sprites/{name}/fs/copy

Copy a file or directory.

Request Body

application/json
source* string
dest* string
workingDir* string
recursive* boolean
preserveAttrs* boolean
asRoot* boolean

Response

application/json
copied* CopyResult[]
count* number
totalBytes* number

Response Codes

200

Success
400

Bad Request - Invalid request body
404

Not Found - Resource not found
500

Internal Server Error
bash 
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/fs/copy" \
  -H "Authorization: Bearer $SPRITES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asRoot":false,"dest":"example","preserveAttrs":false,"recursive":false,"source":"example","workingDir":"example"}'
200 Response 
{
  "count": 1,
  "copied": [],
  "totalBytes": 1
}

Change File Mode

POST /v1/sprites/{name}/fs/chmod

Change file or directory permissions.

Request Body

application/json
path* string
workingDir* string
mode* string
recursive* boolean
asRoot* boolean

Response

application/json
affected* ChmodResult[]
count* number

Response Codes

200

Success
400

Bad Request - Invalid request body
404

Not Found - Resource not found
500

Internal Server Error
bash 
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/fs/chmod" \
  -H "Authorization: Bearer $SPRITES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asRoot":false,"mode":"example","path":"example","recursive":false,"workingDir":"example"}'
200 Response 
{
  "count": 1,
  "affected": []
}

Change File Owner

POST /v1/sprites/{name}/fs/chown

Change file or directory ownership.

Request Body

application/json
path* string
workingDir* string
uid* interface{}
gid* interface{}
recursive* boolean
asRoot* boolean

Response

application/json
affected* ChownResult[]
count* number

Response Codes

200

Success
400

Bad Request - Invalid request body
404

Not Found - Resource not found
500

Internal Server Error
bash 
curl -X POST \
  "https://api.sprites.dev/v1/sprites/{name}/fs/chown" \
  -H "Authorization: Bearer $SPRITES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asRoot":false,"gid":null,"path":"example","recursive":false,"uid":null,"workingDir":"example"}'
200 Response 
{
  "count": 1,
  "affected": []
}

Watch Filesystem

WSS /v1/sprites/{name}/fs/watch

Watch for filesystem changes via WebSocket.

JSON Messages

WatchMessage Client → Server
type* String
paths [String]
recursive boolean
workingDir String
path String
event String
timestamp String
size integer
isDir boolean
message String
WatchMessage Server → Client
type* String
paths [String]
recursive boolean
workingDir String
path String
event String
timestamp String
size integer
isDir boolean
message String

Binary Protocol

In non-PTY mode, binary messages are prefixed with a stream identifier byte. In PTY mode, binary data is sent raw without prefixes.

Binary Frame Format (non-PTY):
Stream ID (1 byte) + Payload (N bytes)
Stream ID Name Direction Description
0 stdin client → server Standard input data
1 stdout server → client Standard output data
2 stderr server → client Standard error data
3 exit server → client Exit code (payload is exit code as byte)
4 stdin_eof client → server End of stdin stream

Response Codes

101

Switching Protocols - WebSocket connection established
400

Bad Request - Invalid WebSocket upgrade or missing parameters
404

Not Found - Resource not found
bash 
websocat \
  "wss://api.sprites.dev/v1/sprites/{name}/fs/watch?path=/bin/bash&tty=true" \
  -H "Authorization: Bearer $SPRITES_TOKEN"
Binary Streams
→ stdin (0x00 + data)
← stdout (0x01 + data)
← stderr (0x02 + data)
JSON Messages

Resize terminal (client → server):

{"type": "resize", "cols": 120, "rows": 40}

Port opened (server → client):

{"type": "port_opened", "port": 8080, "address": "0.0.0.0", "pid": 1234}