Aspenside
Developer API

Build on top of Aspenside

Aspenside runs a local Hono-powered server directly on your desktop machine. This exposes a private, fully capable REST API to manage workspaces, projects, files, and agent state. Build custom terminal scripts, lightweight IDE helpers, or a fully custom frontend to drive your agents.

1. Overview

Because Aspenside is fundamentally built around local-first architectural standards, the agent process runs as a local background daemon. It handles actual terminal executions, file indexing, and database storage locally on your hardware.

Why leverage the REST API?

  • Create custom CLI scripts to inspect your active agent sessions.
  • Automate project-level actions or file-manipulation workflows.
  • Synchronize local directories with customized editors or preview processes.

2. Base URL & Port Discovery

By default, the Aspenside local-first backend daemon runs on your machine. All endpoints are relative to your local base URL:

http://localhost:5678

Note: Depending on configuration or environment overrides, the active port can be customized in your local .env.

3. Authentication

To guarantee your local file-system and workspace are secure, the API implements device authorization safeguards. Requests sent from local scripts must pass the device ID authentication header.

Required Headers
HeaderDescriptionExample
X-Aspenside-Device-IdYour authorized hardware device UUID."dev_macbook_pro_uuid"
Content-TypeMust be set to standard application/json for POST/PATCH bodies."application/json"

4. Files API

The files API gives you direct structural and read/write capabilities across the absolute file path surface of your environment.

GET/api/files/browse

Lists files and directories for a target path. If no path is provided, defaults to the user's home directory.

Query Parameters
pathstring (optional)

The absolute directory path to list. Example: /Users/username/project

Example CURL
curl -H "X-Aspenside-Device-Id: my_device_id" \
  "http://localhost:5678/api/files/browse?path=%2FUsers%2Fmac%2Fproject"
GET/api/files/content

Read the absolute UTF-8 text contents of a local file safely.

Query Parameters
pathstring (required)

The absolute path to the target file.

Example Response
{
  "path": "/Users/mac/project/README.md",
  "content": "# Hello Aspenside\nThis is local-first..."
}
POST/api/files/directory

Creates a directory at the specified absolute path. Automatically acts recursively.

JSON Body Schema
{
  "path": "/Users/mac/project/new-folder"
}
Example Fetch
fetch('http://localhost:5678/api/files/directory', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Aspenside-Device-Id': 'your_device_id'
  },
  body: JSON.stringify({ path: '/Users/mac/project/src' })
})

5. Workspaces API

Workspaces group multiple developer projects and let you manage shared preferences, environment context, and agent configurations together.

GET/api/workspaces

Returns all configured local workspaces, sorted by the most recently updated.

{ "workspaces": [ { "id": "workspace_01", "name": "Frontend Core", "description": "Primary client and landing sites", "preferencesJson": "{}", "createdAt": "2026-06-03T09:00:00.000Z", "updatedAt": "2026-06-03T09:00:00.000Z" } ] }
POST/api/workspaces

Insert a new workspace to orchestrate projects.

Request Schema (JSON)
{
  "name": "Backend Services",
  "description": "Local API development",
  "preferencesJson": {}
}
Response (201 Created)
{
  "workspace": {
    "id": "new_workspace_uuid",
    "name": "Backend Services",
    "description": "Local API development",
    "preferencesJson": "{}",
    "createdAt": "2026-06-03T12:00:00.000Z"
  }
}