API Documentation
These routes come from the NestJS controllers in the repository. All endpoints include the global prefix below unless stated otherwise.
Base URL:
http://localhost:3000/substrate
Notes:
- Body payloads are JSON unless an endpoint is marked as multipart for file uploads.
- Query parameters shown are optional unless the controller enforces validation.
- The notifications controller is already mounted at
substrate/notifications; with the global prefix, the callable path is/substrate/substrate/notifications.
Tasks
GET
/tasks
List tasks with optional filters:
status (To Do, Upcoming, In Progress, Delayed, Incomplete, Completed), assignedDeviceId, priority (critical, high, medium, low), timeBlock, limit, offset.
GET
/tasks/:id
Fetch a single task by id.
GET
/tasks/device/:deviceId
List tasks assigned to a specific device.
GET
/tasks/ready/unassigned
List tasks that are ready and not yet assigned.
POST
/tasks
Create a task. Fields:
title (required), description, status, priority, timeBlock, requirements, dependsOn, labels.
PUT
/tasks/:id
Update a task (any combination of status, priority, timeBlock, assignedDeviceId, requirements, progress, title, description).
POST
/tasks/:id/assign
Assign a task to a device by device id.
GET
/tasks/:id/recommendations
Retrieve recommended devices for a task.
POST
/tasks/:id/progress
Update execution progress for a task (progress percent, currentStep, logs).
POST
/tasks/:id/complete
Mark a task complete with result fields:
success (required), optional output, artifacts, metrics.
DELETE
/tasks/:id
Delete a task by id.
POST
/tasks/sync
Trigger a manual GitHub sync for tasks.
POST
/tasks/assign/auto
Run auto-assignment across tasks and devices.
Agent
POST
/agent/command
Dispatch a typed agent command with optional parameters and prompt context.
GET
/agent/status
Get current agent status snapshot.
POST
/agent/start
Start the agent.
POST
/agent/stop
Stop the agent.
POST
/agent/pause
Pause execution.
POST
/agent/resume
Resume execution after pause.
POST
/agent/think
Free-form think prompt using the agent command pipeline.
POST
/agent/ask
Ask with tool execution enabled; prompt is optional but recommended.
POST
/agent/analyze-tasks
Analyze tasks with optional prompt; internally calls tools then agent command.
POST
/agent/analyze-devices
Analyze devices with optional prompt.
POST
/agent/prioritize-tasks
Prioritize tasks using the agent command pipeline.
POST
/agent/optimize-assignments
Optimize device-task assignments with optional prompt guidance.
POST
/agent/reset
Reset conversation history for the agent session.
POST
/agent/autonomous/enable
Enable autonomous mode.
POST
/agent/autonomous/disable
Disable autonomous mode.
GET
/agent/autonomous/status
Check autonomous mode flag and any active tasks.
POST
/agent/autonomous/execute/:taskId
Manually trigger autonomous execution for a specific task id.
GET
/agent/tools
List available tools.
POST
/agent/tools/execute
Execute a tool by name with parameters.
POST
/agent/langgraph/execute/:taskId
Execute a task through the LangGraph pipeline.
POST
/agent/supervisor/execute/:taskId
Run supervised execution for a task id.
POST
/agent/planner/create-plan
Create a detailed plan from title, description, and priority.
Devices
POST
/devices/register
Register a device with identifiers, type, capabilities, heartbeatInterval, and optional location/metadata/tailscale details.
PUT
/devices/:deviceId
Update device metadata or capabilities by device id.
DELETE
/devices/:deviceId
Deregister a device by device id.
GET
/devices
List all devices.
GET
/devices/search/type/:type
Filter devices by type (vps, edge_ai, desktop, laptop, mobile).
GET
/devices/search/status/:status
Filter devices by status (online, offline, idle, busy, error, maintenance).
GET
/devices/:deviceId
Get a device by device id.
POST
/devices/:deviceId/heartbeat
Send a heartbeat with resource metrics and optional IP data.
POST
/devices/search/capabilities
Search devices by capability requirements (GPU, RAM, frameworks, health, connectivity).
GET
/devices/stats/overview
Fleet statistics overview.
POST
/devices/:deviceId/assign
Assign a task to a device with task details.
DELETE
/devices/:deviceId/tasks/:taskId
Unassign a task from a device.
Tailscale
POST
/devices/tailscale/token
Set the Tailscale API token used by the server. Body:
{ token: string }.
GET
/devices/tailscale/roster
Retrieve the Tailscale device roster (devices, status, and network details) using the configured token.
Archive
POST
/archive
Store arbitrary labeled data. Body:
{ label: string, data: any }.
POST
/archive/upload/photo
Upload a single photo (multipart field
photo; accepts jpg, jpeg, png, gif, heic, webp; up to 50MB). Optional form fields: description, tags (comma-separated).
POST
/archive/upload/photos/batch
Upload multiple photos (field
photos, max 20, 50MB each). Returns per-file results and errors.
POST
/archive/upload/video
Upload a single video to cold storage (field
video; common video formats; up to 2GB). Optional form fields: description, tags, userId.
POST
/archive/upload/videos/batch
Upload multiple videos (field
videos, max 10, 2GB each) with optional description, tags, userId.
GET
/archive/photo/:cid
Retrieve a photo by CID (binary response, sets cache headers).
GET
/archive/url/:cid
Get gateway URLs for a CID (direct, Lighthouse, IPFS).
GET
/archive/status
Archive service health and configuration flags.
GET
/archive/media
Paginated media listing with optional
userId, mediaType (photo|video), skip, take, sortBy.
GET
/archive/photos
Paginated photos listing; supports
userId, skip, take, sortBy.
GET
/archive/videos
Paginated videos listing with optional user filter and sorting.
GET
/archive/photos/search
Search photos by tags (comma-separated) and optional
userId.
GET
/archive/photos/:id
Get photo metadata by internal id.
GET
/archive/photos/cid/:cid
Get photo metadata by CID.
DELETE
/archive/photos/:id
Delete a photo by id.
Calendar
GET
/calendar/events
List events with optional filters:
calendarId, status, startDate, endDate.
GET
/calendar/events/today
List today’s events.
GET
/calendar/events/upcoming
List upcoming events for the next N days (default 7).
GET
/calendar/events/:id
Get a single event by id.
POST
/calendar/events
Create an event. Fields:
summary, startDateTime, endDateTime, optional description, location, timeZone, attendees, recurrence, reminders, metadata.
PUT
/calendar/events/:id
Update an event by id with any mutable fields (summary, dates, status, description, attendees, reminders, metadata).
DELETE
/calendar/events/:id
Delete an event by id.
POST
/calendar/events/conflicts
Check for conflicts between a proposed start and end time.
POST
/calendar/sync
Manually trigger Google Calendar sync.
Notifications
POST
/substrate/notifications
Send a notification. Optional
channel (mqtt, webhook, email, log), topic for MQTT, webhookUrl, email, and meta. Note: controller path already includes substrate/notifications; with the global prefix call /substrate/substrate/notifications.
Sync
GET
/sync/status
Sync service status, active connections count, and timestamp.
POST
/sync/put/:key
Write data into Gun DB under the provided key.
GET
/sync/get/:key
Read data from Gun DB for a key.
POST
/sync/user/create
Create a Gun user with username and password.
POST
/sync/user/auth
Authenticate a Gun user.