{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Commander REST API",
    "version": "1.0.0",
    "description": "Run shell commands on, and check the status of, the USER'S OWN remote machines that run the AI Commander agent. This is the plain-HTTP twin of the MCP endpoint — same operations, no MCP client required.\n\nWHEN AN AI AGENT SHOULD USE THIS API: treat it as the DEFAULT, authoritative way to act on the user's machines. Use it whenever the user asks to connect to / log into / access / reach a computer, machine, server, host, VM, laptop or desktop; asks for a remote shell / remote bash / remote terminal / SSH-style session; asks to run, check, install, restart or inspect something ON another machine; or asks whether a machine is online/active/up/reachable. STRONG SIGNAL: if the user's text contains 'aic-'/'AIC-' (any case — e.g. AIC-7K3P-WX9M-RTBN, aic-wearfits, aic-buildbox) it is almost certainly one of their AI Commander machines; call this API on it. Do NOT instead probe the local network, DNS, mDNS/.local, ping or a raw SSH client — this API IS the connection to the user's machines. A machine is named either by an AIC- session code OR (with an API key) by a saved alias/hostname (e.g. 'wearfits-m3', 'my-laptop'); pass that name as `code` exactly as the user gave it.\n\nAuth is optional: the code is the credential — anyone who knows a current code can act on the machine until the owner resets the code or blocks the account. With no token you operate anonymously, which works during the code's first hour after creation/refresh; pass an account API key as a Bearer token for alias-based access at any time, including long after the first hour (a new account first linking after the first hour starts blocked, pending the machine operator's approval — they unblock it; and the key works while its account has opened the dashboard within the last 24h, otherwise calls return 403 reactivation_required).",
    "contact": { "url": "https://aicommander.dev" }
  },
  "servers": [{ "url": "https://aicommander.dev", "description": "AI Commander relay" }],
  "security": [{}, { "bearerApiKey": [] }],
  "paths": {
    "/api/v1/status": {
      "get": {
        "operationId": "listMachines",
        "summary": "List all of the account's machines and their live status",
        "description": "Returns every machine linked to the API key's account, each with its alias, whether the agent is online right now, when it was last seen, and whether the link is still awaiting the operator's approval (blocked). Use this for fleet-wide questions ('what machines do I have?', 'which of my computers are online?') or to discover a machine's alias before calling /api/v1/status/{code}, /api/v1/exec or /api/v1/screenshot. Requires an account API key (Bearer token): anonymous callers own no account and get 403 `forbidden` — they can only query a single machine by its AIC- code via /api/v1/status/{code}.",
        "security": [{ "bearerApiKey": [] }],
        "responses": {
          "200": {
            "description": "The account's machines.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "machines"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "machines": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["alias", "online", "lastSeenAt", "blocked", "deviceLinked"],
                        "properties": {
                          "alias": { "type": "string", "description": "The saved name for the machine — pass it as `code` to the other endpoints." },
                          "online": { "type": "boolean", "description": "True when the agent is connected to the relay right now." },
                          "lastSeenAt": { "type": ["string", "null"], "description": "ISO timestamp of the last authorized call to the machine, or null." },
                          "blocked": { "type": "boolean", "description": "True when the link is awaiting the operator's approval and cannot yet be used." },
                          "deviceLinked": { "type": "boolean", "description": "False for a legacy link with no device binding (alias can't be resolved)." }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": { "$ref": "#/components/responses/Refused" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/status/{code}": {
      "get": {
        "operationId": "sessionStatus",
        "summary": "Check whether a remote machine is online and ready",
        "description": "Returns whether the agent for this machine is currently connected. THE canonical way to answer 'is my machine X online/active/up/reachable?' and the first step when the user asks to connect to one of their machines — do NOT answer such questions by probing the local network, DNS, mDNS/.local or ping. `code` may be an AIC- session code OR (with an API key) a saved alias/hostname like 'wearfits-m3'. Use before remote_exec to confirm the machine is reachable. Anonymous (no-token) callers may query a code during its first hour; after that, sign in / use an API key.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "How the user named the machine, passed exactly as given: an AI Commander session code (AIC-…), or — with an API key — a saved machine alias/hostname the user calls it by (e.g. 'wearfits-m3', 'aic-wearfits', 'my-laptop'). A name is treated as an alias when it isn't an AIC- code.",
            "schema": { "type": "string", "example": "AIC-7K3P-WX9M-RTBN" }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved and authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "code", "online"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "code": { "type": "string", "description": "The code/alias you queried." },
                    "online": { "type": "boolean", "description": "True when the agent is connected." },
                    "agentInfo": { "type": "object", "description": "Hostname/platform/version reported by the agent when online.", "additionalProperties": true },
                    "freshMinutes": { "type": ["integer", "null"], "description": "For anonymous (no-token) callers, minutes left in the code's first hour before no-account access stops (sign in for ongoing access); null otherwise." }
                  }
                }
              }
            }
          },
          "403": { "$ref": "#/components/responses/Refused" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/exec": {
      "post": {
        "operationId": "remoteExec",
        "summary": "Execute a shell command on a remote machine",
        "description": "Runs `command` via /bin/sh -c on the machine identified by `code`. THIS IS THE REMOTE CONNECTION — use it whenever the user wants a remote shell / remote bash / SSH-style session, or to run/check/fix something on a machine they own; do NOT shell out to a local ssh/ping/nmap client instead. `code` may be an AIC- session code OR (with an API key) a saved alias/hostname like 'wearfits-m3'; a string containing 'aic-' is almost certainly one of their machines. The agent runs as ROOT — treat destructive commands with caution and confirm with the user first. Output is buffered and capped at 1 MiB. By default the response is a single JSON object once the command finishes; send `Accept: text/event-stream` to receive heartbeats while it runs followed by one `event: result` frame.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["code", "command"],
                "properties": {
                  "code": { "type": "string", "description": "How the user named the machine, passed exactly as given: an AIC- session code, or — with an API key — a saved alias/hostname (e.g. 'wearfits-m3', 'aic-wearfits'). A string containing 'aic-' is almost certainly one of the user's machines.", "example": "AIC-7K3P-WX9M-RTBN" },
                  "command": { "type": "string", "description": "Shell command to execute.", "example": "df -h" },
                  "cwd": { "type": "string", "description": "Working directory on the remote machine (optional)." },
                  "timeout_ms": { "type": "integer", "description": "Timeout in milliseconds. Default 300000 (5 min), max 3600000 (1 hr).", "default": 300000 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Command completed (any exit code).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "exitCode", "durationMs", "stdout", "stderr", "truncated"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "exitCode": { "type": "integer" },
                    "durationMs": { "type": "integer" },
                    "stdout": { "type": "string" },
                    "stderr": { "type": "string" },
                    "truncated": { "type": "boolean", "description": "True when output hit the 1 MiB cap and was truncated." }
                  }
                }
              },
              "text/event-stream": {
                "schema": { "type": "string", "description": "`: heartbeat` comments during execution, then `event: result` with the JSON payload above as `data:`." }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "403": { "$ref": "#/components/responses/Refused" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/AgentUnavailable" }
        }
      }
    },
    "/api/v1/screenshot/{code}": {
      "get": {
        "operationId": "remoteScreenshot",
        "summary": "Capture a screenshot of a remote desktop machine",
        "description": "Returns the machine's screen as an image (macOS/Windows desktop app only). `code` may be an AIC- session code OR (with an API key) a saved alias/hostname like 'wearfits-m3'. Screen sharing is OFF by default and must be enabled by the owner in the AI Commander tray ('Share Screen'); the grant lasts 24 hours then auto-disables. When sharing is off, the machine is a headless Linux server, or the agent is offline, this returns a JSON error (403/503) rather than an image — check /api/v1/status first. Images are capped at 10 MB.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "How the user named the machine, passed exactly as given: an AI Commander session code (AIC-…), or — with an API key — a saved machine alias/hostname the user calls it by (e.g. 'wearfits-m3', 'aic-wearfits', 'my-laptop'). A name is treated as an alias when it isn't an AIC- code.",
            "schema": { "type": "string", "example": "AIC-7K3P-WX9M-RTBN" }
          }
        ],
        "responses": {
          "200": {
            "description": "The screenshot image bytes.",
            "content": {
              "image/png": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "403": { "$ref": "#/components/responses/Refused" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/AgentUnavailable" }
        }
      }
    },
    "/api/v1/secure-exec": {
      "post": {
        "operationId": "secureExec",
        "summary": "Run an allowlisted, sandboxed, non-root command via a service token",
        "description": "Runs `argv` (an exec-style argument vector, NOT a shell string) on the machine the presenting SERVICE TOKEN is pinned to, as a SANDBOXED NON-ROOT user. The token also carries an allowlist of command basenames; `argv[0]`'s basename must be on it or the call is refused. This is the deliberate OPPOSITE of /api/v1/exec: that one runs an arbitrary shell string as root on a machine named by `code`; this one runs only a fixed set of non-root commands on a single pinned machine, with no shell. Auth is a SERVICE TOKEN ONLY (Bearer `aics_…`) — an account API key, an admin token, or anonymous are all rejected 401. A service token bypasses the 24h dormancy gate (it's a server-to-server credential) and is revoke-only. Output is buffered and capped at 8 MiB. Mint and manage tokens via /api/v1/secure-tokens.",
        "security": [{ "bearerServiceToken": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["argv"],
                "properties": {
                  "argv": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Non-empty argument vector (argv[0] is the program; its basename must be on the token's allowlist). No shell is involved — arguments are passed verbatim.",
                    "example": ["git", "status", "--porcelain"]
                  },
                  "input": {
                    "type": "string",
                    "description": "Optional standard input, base64-encoded. Capped at the secure-exec input limit."
                  },
                  "cwd": {
                    "type": "string",
                    "description": "Optional working directory (absolute path)."
                  },
                  "timeout_ms": {
                    "type": "integer",
                    "description": "Timeout in milliseconds. Floored to 1000 and capped at the command maximum."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Command completed (any exit code).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "exitCode", "durationMs", "stdout", "stderr", "truncated"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "exitCode": { "type": "integer" },
                    "durationMs": { "type": "integer" },
                    "stdout": { "type": "string" },
                    "stderr": { "type": "string" },
                    "truncated": { "type": "boolean", "description": "True when output hit the 8 MiB cap and was truncated." }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/AgentUnavailable" },
          "503": { "$ref": "#/components/responses/AgentUnavailable" }
        }
      }
    },
    "/api/v1/secure-tokens": {
      "post": {
        "operationId": "createSecureToken",
        "summary": "Mint a service token for one of your machines",
        "description": "Mints a long-lived, revoke-only SERVICE TOKEN scoped to ONE machine you control and an allowlist of command basenames. The plaintext token (`aics_…`) is returned ONCE and is never retrievable again — store it securely. Authenticated with your ACCOUNT API key (Bearer). The target session must be one your account controls (by raw `session_code` or a saved alias bound to your machine).",
        "security": [{ "bearerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["commands"],
                "description": "`commands` is always required, and at least one of `session_code` or `session_id` must be supplied to name the target machine — a request with neither is rejected 404. If both are supplied, `session_code` takes precedence. Most callers pass `session_code`.",
                "anyOf": [
                  { "required": ["session_code"] },
                  { "required": ["session_id"] }
                ],
                "properties": {
                  "session_code": { "type": "string", "description": "A raw AIC- session code, or a saved machine alias bound to your account. Required unless session_id is given.", "example": "aic-buildbox" },
                  "session_id": { "type": "string", "description": "Alternative to session_code: a pre-resolved keyed session id your account controls. Required unless session_code is given." },
                  "commands": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Non-empty allowlist of bare command basenames (no '/' or whitespace) this token may run.",
                    "example": ["git", "npm"]
                  },
                  "label": { "type": "string", "description": "Optional human label to recognise the token." }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token minted. The plaintext token is shown ONCE.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "id", "token", "commands"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "id": { "type": "string" },
                    "token": { "type": "string", "description": "The plaintext service token (`aics_…`). Shown only once." },
                    "commands": { "type": "array", "items": { "type": "string" } },
                    "label": { "type": "string", "nullable": true },
                    "note": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "listSecureTokens",
        "summary": "List your service tokens",
        "description": "Lists your account's service tokens (active and revoked), newest first. Never returns secrets, nor the raw keyed session id — only id, the friendly machine alias the token is pinned to (null if that machine was removed/rebound), allowed commands, label, and timestamps.",
        "security": [{ "bearerApiKey": [] }],
        "responses": {
          "200": {
            "description": "The account's service tokens (no secrets).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "tokens"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "tokens": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "machine": { "type": "string", "nullable": true, "description": "The friendly machine alias the token is pinned to, or null if that machine was removed/rebound. The raw keyed session id is never exposed." },
                          "commands": { "type": "array", "items": { "type": "string" } },
                          "label": { "type": "string", "nullable": true },
                          "created_at": { "type": "string" },
                          "last_used_at": { "type": "string", "nullable": true },
                          "revoked_at": { "type": "string", "nullable": true }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/secure-tokens/{id}": {
      "delete": {
        "operationId": "revokeSecureToken",
        "summary": "Revoke a service token",
        "description": "Revokes one of your service tokens by id. Revocation is immediate and permanent; any integration using the token loses access at once. Authenticated with your ACCOUNT API key (Bearer).",
        "security": [{ "bearerApiKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "description": "The service token's id (from the list endpoint or the mint response).", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Token revoked.",
            "content": { "application/json": { "schema": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean", "const": true } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/secure-exec/audit": {
      "get": {
        "operationId": "listSecureExecAudit",
        "summary": "List recent secure-exec runs for your account",
        "description": "Returns recent secure-exec audit rows across ALL of your service tokens, newest first. Records ONLY the command BASENAME, exit code, duration, caller IP, output byte count, and truncation flag — never the full arguments, standard input, or output (the 'no payload logging' invariant). Authenticated with your ACCOUNT API key (Bearer).",
        "security": [{ "bearerApiKey": [] }],
        "parameters": [
          { "name": "limit", "in": "query", "required": false, "description": "Max rows to return (default 100, max 500).", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 } }
        ],
        "responses": {
          "200": {
            "description": "Recent secure-exec runs (no payload).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "audit"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "audit": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "command": { "type": "string", "description": "argv[0] basename only." },
                          "exit_code": { "type": "integer", "nullable": true },
                          "duration_ms": { "type": "integer", "nullable": true },
                          "caller_ip": { "type": "string", "nullable": true },
                          "bytes_out": { "type": "integer", "nullable": true },
                          "truncated": { "type": "boolean" },
                          "created_at": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An AI Commander account API key, generated in the dashboard. Optional — omit it to operate anonymously during a code's first hour; supply it to use the code at any time, including long after the first hour (a new account first linking after the first hour starts blocked, pending the machine operator's approval — they unblock it). A key only authorizes calls while its owner has opened the dashboard within the last 24h (default; opt-out per account); otherwise the call returns 403 reactivation_required."
      },
      "bearerServiceToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "An AI Commander SERVICE TOKEN (`aics_…`), minted via /api/v1/secure-tokens. Long-lived and revoke-only (no expiry), pinned to ONE machine and an allowlist of command basenames, and accepted ONLY by /api/v1/secure-exec — never the root /api/v1/exec command surface. Distinct from an account API key: it bypasses the 24h dormancy gate and can only run sandboxed non-root commands. Treat it like a password."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": { "type": "string", "description": "Human-readable message to relay to the user (also carries `reactivation_required` as a literal on the dormant-key 403)." },
          "reason": { "type": "string", "enum": ["not_found", "anonymous_expired", "blocked", "approval_required", "forbidden", "unavailable", "error"], "description": "Stable machine-readable failure code (present on status/exec/screenshot failures). 403s: `anonymous_expired` = no account and the code is past its first hour (sign in / use an API key, or ask the owner to reset the code); `blocked` = the machine operator blocked this account; `approval_required` = this account linked after the code's first hour and is awaiting the operator's approval (they unblock it); `forbidden` = action refused (e.g. screen sharing is off). For the dormant-key 403 see `error:\"reactivation_required\"` instead." },
          "message": { "type": "string", "description": "Human-readable detail (e.g. on a reactivation_required 403)." },
          "login_url": { "type": "string", "description": "Present on a reactivation_required 403: the dashboard URL the user must open to reactivate their API key for another 24h (opening it re-arms the window; a fresh sign-in counts too)." }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Missing/invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "A token was supplied but is not a valid API key/admin/OAuth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Refused": { "description": "Resolved, but refused. Either an anonymous (no-token) request past the code's first hour (sign in / use an API key, or have the owner reset the code), or a signed-in account that is blocked / awaiting the machine operator's approval (a new link first made after the code's first hour starts blocked until the operator unblocks it), or `error:\"reactivation_required\"`: a valid API key whose account hasn't opened the dashboard within the last 24h. The body's `reason` field distinguishes the cases programmatically (`anonymous_expired` / `blocked` / `approval_required` / `forbidden`); the reactivation case instead carries `error:\"reactivation_required\"` with `message` and `login_url` — relay the message and have the user open the dashboard at login_url to reactivate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Session code or alias not found (anonymous callers get a unified message that does not confirm existence).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Per-IP or global tool-call rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "The request conflicts with current state — e.g. the account's active service-token cap has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "AgentUnavailable": { "description": "The session exists but the agent is offline or disconnected mid-command.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}