API Reference

OpenBoot provides a REST API for programmatic access to configs, package search, and utilities. All endpoints are hosted at https://openboot.dev.

Base URL

https://openboot.dev

Authentication

Some endpoints require authentication. Include your auth token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Get your token by running openboot login — it’s saved to ~/.openboot/auth.json.

Configs

List User Configs

Get all configs for the authenticated user.

GET /api/configs

Auth required: Yes

Response:

[
  {
    "id": "cfg_abc123",
    "slug": "my-setup",
    "name": "My Dev Setup",
    "description": "Personal development environment",
    "visibility": "unlisted",
    "install_count": 12,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-02-10T14:20:00Z"
  }
]

Get Config

Get a specific config by username and slug. Public and unlisted configs are accessible without auth. Private configs require authentication and ownership.

GET /api/configs/:slug

Auth required: Only for private configs

Response:

{
  "id": "cfg_abc123",
  "slug": "my-setup",
  "name": "My Dev Setup",
  "description": "Personal development environment",
  "base_preset": "developer",
  "packages": [
    { "name": "node", "type": "formula", "desc": "JavaScript runtime built on V8 engine" }
  ],
  "custom_script": "mkdir -p ~/projects",
  "dotfiles_repo": "https://github.com/user/dotfiles.git",
  "visibility": "unlisted"
}

Create Config

Create a new config.

POST /api/configs

Auth required: Yes

Request body:

{
  "name": "My Setup",
  "description": "Dev environment",
  "base_preset": "developer",
  "packages": [
    { "name": "node", "type": "formula" }
  ],
  "visibility": "unlisted"
}

Response:

{
  "id": "cfg_abc123",
  "slug": "my-setup"
}

Update Config

Update an existing config.

PUT /api/configs/:slug

Auth required: Yes (must own the config)

Request body: Same as create (all fields optional)

Response: Updated config object

Delete Config

Delete a config.

DELETE /api/configs/:slug

Auth required: Yes (must own the config)

Response: 204 No Content

Create Config from Snapshot

Upload a snapshot captured by openboot snapshot to create a config.

POST /api/configs/from-snapshot

Auth required: Yes

Request body:

{
  "name": "My Mac Setup",
  "snapshot": {
    "packages": {
      "formulae": ["node", "go"],
      "casks": ["visual-studio-code"],
      "npm": ["typescript"],
      "taps": ["homebrew/cask-fonts"]
    },
    "macos_prefs": [...],
    "shell": {...},
    "git": {...}
  }
}

Response:

{
  "slug": "my-mac-setup"
}

Config Pages

Get Config JSON

Get the full config data for a username/slug combination.

GET /:username/:slug/config

Auth required: Only for private configs

Response: Config object (same as GET /api/configs/:slug)

Get Install Script

Get the shell install script for a config.

GET /:username/:slug/install

Auth required: Only for private configs (redirects to browser auth flow if unauthenticated)

Response: Shell script (Content-Type: text/x-shellscript)

#!/bin/bash
# OpenBoot install script for username/slug
# ...

Package Catalog

List All Packages

Returns the complete package catalog with metadata. Used by the CLI to fetch package descriptions and installer types. Responses are cached (1h client, 24h CDN).

GET /api/packages

Auth required: No

Response:

{
  "packages": [
    {
      "name": "git",
      "desc": "Distributed version control system",
      "category": "essential",
      "type": "cli",
      "installer": "formula"
    },
    {
      "name": "visual-studio-code",
      "desc": "Code editor with extensions and debugging",
      "category": "essential",
      "type": "gui",
      "installer": "cask"
    },
    {
      "name": "typescript",
      "desc": "Typed superset of JavaScript",
      "category": "essential",
      "type": "language",
      "installer": "npm"
    }
  ]
}

Fields:

• name — Package identifier
• desc — Human-readable description
• category — essential, development, productivity, or optional
• type — Package kind: cli, gui, language, devops, or database
• installer — Install method: formula (Homebrew), cask (Homebrew Cask), or npm

Package Search

Search Homebrew Packages

Search for Homebrew formulae and casks.

GET /api/homebrew/search?q=<query>

Auth required: No

Query parameters:

• q — Search query

Response:

{
  "formulae": [
    { "name": "node", "desc": "JavaScript runtime" }
  ],
  "casks": [
    { "name": "visual-studio-code", "desc": "Code editor" }
  ]
}

Search NPM Packages

Search for npm packages.

GET /api/npm/search?q=<query>

Auth required: No

Query parameters:

• q — Search query

Response:

{
  "packages": [
    { "name": "typescript", "description": "TypeScript language" }
  ]
}

Utilities

Parse Brewfile

Parse a Brewfile and extract package lists.

POST /api/brewfile/parse

Auth required: No

Request body:

brew "node"
brew "go"
cask "visual-studio-code"

Response:

{
  "formulae": ["node", "go"],
  "casks": ["visual-studio-code"],
  "taps": []
}

Authentication

Get Current User

Get the authenticated user’s information.

GET /api/user

Auth required: Yes

Response:

{
  "id": "usr_abc123",
  "username": "johndoe",
  "email": "john@example.com",
  "avatar_url": "https://...",
  "oauth_provider": "github"
}

Rate Limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1234567890

Visibility Modes

Configs have three visibility levels that control access:

For private configs, run openboot login first to authenticate before installing.

Error Responses

All errors return JSON with an error field:

{
  "error": "Config not found"
}

HTTP Status Codes:

Examples

Create a Config

TOKEN=$(cat ~/.openboot/auth.json | jq -r '.token')

curl -X POST https://openboot.dev/api/configs 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "My Setup",
    "base_preset": "developer",
    "packages": [
      {"name": "node", "type": "formula", "desc": "JavaScript runtime"},
      {"name": "visual-studio-code", "type": "cask", "desc": "Code editor"}
    ]
  }'

Search Packages

curl "https://openboot.dev/api/homebrew/search?q=docker"

Get Config JSON

curl https://openboot.dev/johndoe/my-setup/config

See also: CLI Reference for the openboot command-line tool.