API Reference

Complete reference for the SwarmStack REST API. All endpoints except /api/health require Bearer token authentication.

Base URL: https://api.swarmstack.net

Files API

Read, write, search, and manage files on the server.

GET /api/files/read

Read contents of a file from the server.

Query Parameters

Name	Type	Description
path required	string	Absolute path to the file
encoding	string	File encoding (default: utf-8)

POST /api/files/write

Write content to a file.

Request Body

Name	Type	Description
path required	string	Absolute path for the file
content required	string	Content to write

GET /api/ls

List directory contents with detailed file information.

Query Parameters

Name	Type	Description
path required	string	Directory path to list

GET /api/files/search

Search for files matching a pattern.

Query Parameters

Name	Type	Description
path required	string	Root directory to search
pattern required	string	Search pattern (glob or regex)

DELETE /api/files

Delete a file or directory.

Query Parameters

Name	Type	Description
path required	string	Path to delete

POST /api/mkdir

Create a new directory (with parents if needed).

Request Body

Name	Type	Description
path required	string	Directory path to create

Git API

Git operations for version control integration.

GET /api/git/status

Get repository status (staged, modified, untracked files).

Query Parameters

Name	Type	Description
path required	string	Repository path

GET /api/git/diff

Get diff of changes in the repository.

GET /api/git/log

Get commit history.

GET /api/git/branch

List branches or get current branch.

POST /api/git/add

Stage files for commit.

Request Body

Name	Type	Description
path required	string	Repository path
files	string[]	Files to stage (default: all)

POST /api/git/commit

Create a commit with staged changes.

Request Body

Name	Type	Description
path required	string	Repository path
message required	string	Commit message

POST /api/git/push

Push commits to remote repository.

POST /api/git/pull

Pull changes from remote repository.

Swarm API

Manage Firecracker microVMs for AI agent execution.

GET /api/swarm/status

Get status of all running VMs including PID, IP, and uptime.

POST /api/swarm/boot

Boot one or more Firecracker microVMs using snapshot restoration (~8ms per VM).

Request Body

Name	Type	Description
count	number	Number of VMs to boot (default: 1)

POST /api/swarm/cleanup

Terminate all running VMs and clean up resources.

DELETE /api/swarm/vm/:pid

Terminate a specific VM by process ID.

Path Parameters

Name	Type	Description
pid required	number	VM process ID

Tickets API

Work ticket management for agent task orchestration.

GET /api/tickets

List all tickets with optional filtering.

Query Parameters

Name	Type	Description
status	string	Filter by status (pending, in_progress, completed, failed)
priority	string	Filter by priority (low, medium, high, critical)

GET /api/tickets/:id

Get a specific ticket by ID.

POST /api/tickets

Create a new ticket for agent work.

Request Body

Name	Type	Description
title required	string	Ticket title
description	string	Detailed description
priority	string	low, medium, high, critical
dependencies	string[]	IDs of prerequisite tickets

PATCH /api/tickets/:id

Update ticket status, assignment, or other fields.

Request Body

Name	Type	Description
status	string	New status
assignee	string	Agent ID claiming the ticket
result	object	Work output/results

DELETE /api/tickets/:id

Delete a ticket.

Admin API

Administrative operations (elevated permissions required).

POST /api/exec

Execute a shell command on the server.

Request Body

Name	Type	Description
command required	string	Shell command to execute
cwd	string	Working directory
timeout	number	Timeout in milliseconds

POST /api/admin/restart

Restart the API server (PM2 managed).