Filesystem API

WebSocket Endpoints — Some endpoints in this section use WebSocket for bidirectional communication. The SDK handles the connection protocol automatically.

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

Responses

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

Request

HTTP

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/read"

---

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:optionalstring

File permissions in octal (e.g., '0644')

mkdir:optionalboolean

Create parent directories if they don't exist

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

HTTP

curl -X PUT \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/write"

---

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

Responses

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

Request

HTTP

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/list"

---

Delete File or Directory

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

Delete a file or directory.

Request Body

path:string

workingDir:string

recursive:boolean

asRoot:boolean

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

HTTP

curl -X DELETE \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/delete"

---

Rename File or Directory

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

Rename or move a file or directory.

Request Body

source:string

dest:string

workingDir:string

asRoot:boolean

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

HTTP

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"source":"my-source","dest":"my-dest","workingDir":"my-workingdir"}' \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/rename"

---

Copy File or Directory

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

Copy a file or directory.

Request Body

source:string

dest:string

workingDir:string

recursive:boolean

preserveAttrs:boolean

asRoot:boolean

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

HTTP

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"source":"my-source","dest":"my-dest","workingDir":"my-workingdir"}' \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/copy"

---

Change File Mode

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

Change file or directory permissions.

Request Body

path:string

workingDir:string

mode:string

recursive:boolean

asRoot:boolean

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

HTTP

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"my-path","workingDir":"my-workingdir","mode":"my-mode"}' \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/chmod"

---

Change File Owner

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

Change file or directory ownership.

Request Body

path:string

workingDir:string

uid:any

gid:any

recursive:boolean

asRoot:boolean

Responses

Status	Description
200	Success
400	Bad Request - Invalid request body
404	Not Found - Resource not found
500	Internal Server Error

Request

HTTP

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"my-path","workingDir":"my-workingdir"}' \
"https://api.sprites.dev/v1/sprites/$SPRITE_NAME/fs/chown"

---

Watch Filesystem

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

Watch for filesystem changes via WebSocket.

Responses

Status	Description
101	Switching Protocols - WebSocket connection established
400	Bad Request - Invalid WebSocket upgrade or missing parameters
404	Not Found - Resource not found

Client → Server Messages

WatchMessage

Field	Type	Description
type	string
paths	string[]
recursive	boolean
workingDir	string
path	string
event	string
timestamp	string
size	number
isDir	boolean
message	string

Server → Client Messages

WatchMessage

Field	Type	Description
type	string
paths	string[]
recursive	boolean
workingDir	string
path	string
event	string
timestamp	string
size	number
isDir	boolean
message	string

Request

HTTP

websocat \
"wss://api.sprites.dev/v1/sprites/{name}/fs/watch" \
-H "Authorization: Bearer $SPRITES_TOKEN"

---