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

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

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

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

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

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

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

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

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