Platform signals

Base URL https://app.mandala.computer/api/v1. Every request carries an API key, and failures take the shape under Errors.

GET`/computers/{id}/signals`

Read passive platform signalsmember+

Member-only, finite reads of daemon facts. No guest connection, wake, watcher, output read or Activity capture. An absent or empty since starts at the current head with baseline:true and no history. Replay uses the full opaque cursor; it advances past filtered rows. An expired, malformed, restarted or migrated epoch returns an explicit gap with a new head. These are ephemeral observations, not durable history, complete process coverage or task-success proof. Pages contain at most 100 events and 65536 encoded bytes. Query strings are at most 4096 characters; unknown or duplicate parameters are refused. Both emission scope and current daemon scope must match. Requests have finite routing/body deadlines and may fail unavailable; failures never become empty history. Responses are no-store.

Set MANDALA_API_KEY to your bearer key. MANDALA_BASE_URL, when set, is the full API base including /api/v1. Replace the illustrative resource IDs with yours. These pinned 0.16.0 SDK and direct HTTP examples do not read saved device-login credentials. SDK setup first GETs the computer. Python start/stop/suspend/restart also refresh it with another GET; TypeScript refreshes only if the action returns an acknowledgement.

curl

base_url="${MANDALA_BASE_URL:-}"
if [ -z "$base_url" ]; then base_url='https://app.mandala.computer/api/v1'; fi
curl --fail-with-body "${base_url%/}"'/computers/vm-a1b2c3d4e5f6/signals' \
  -H "Authorization: Bearer $MANDALA_API_KEY"

Python — Mandala SDK 0.16.0

# Python 3.10+: pip install mandala-computer==0.16.0
import os
from mandala_computer import Client

with Client(api_key=os.environ["MANDALA_API_KEY"], base_url=os.environ.get("MANDALA_BASE_URL") or "https://app.mandala.computer/api/v1") as client:
    id = "vm-a1b2c3d4e5f6"
    c = client.computers.get(id)
    result = c.signals()
    print(result)

TypeScript — Mandala SDK 0.16.0

// Node.js 22+: npm install mandala-computer@0.16.0
import { Client } from "mandala-computer";

const apiKey = process.env.MANDALA_API_KEY;
if (!apiKey) throw new Error("Set MANDALA_API_KEY");
const client = new Client({apiKey, baseUrl: process.env.MANDALA_BASE_URL || "https://app.mandala.computer/api/v1"});
const id = "vm-a1b2c3d4e5f6";
const c = await client.computers.get(id);
const result = await c.signals();
console.log(JSON.stringify(result, null, 2));

200 Illustrative successful response.

HTTP 200
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17

{
  "computer": "vm-a1b2c3d4e5f6",
  "from": "dljjqbv5mo00:0",
  "cursor": "dljjqbv5mo00:0",
  "events": [],
  "more": false,
  "baseline": true,
  "supported": [
    "process.exited",
    "computer.started",
    "computer.stopped",
    "computer.suspended",
    "computer.idle"
  ],
  "retention": "ephemeral"
}

401 Platform bearer credential missing.

HTTP 401
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
WWW-Authenticate: Bearer

{
  "error": "Authentication required",
  "reason": "missing",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

401 Platform bearer credential invalid.

HTTP 401
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
WWW-Authenticate: Bearer error="invalid_token"

{
  "error": "invalid API key",
  "reason": "invalid",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

401 Platform bearer credential revoked.

HTTP 401
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
WWW-Authenticate: Bearer error="invalid_token"

{
  "error": "API key revoked",
  "reason": "revoked",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

405 Unsupported method on this public path; HEAD returns these headers without a body.

HTTP 405
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
Allow: GET, HEAD, OPTIONS

{
  "error": "method not allowed",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

Path parameters

idrequired

string

The computer id.

Query parameters

`since`	string	Opaque cursor from the previous page. Missing or empty establishes a head-only baseline.
`limit`	integer	Maximum eligible events on this page.

Response

A safe baseline, finite replay page or explicit reset gap.

Response fields

`computer`always	string
`from`always	string	Opaque start checkpoint, or current head on baseline/reset.
`cursor`always	string	Next opaque checkpoint, including filtered-out ring rows.
`events`always	PlatformSignal[]
`more`always	boolean	Another eligible event is owed; poll with cursor.
`baseline`always	boolean	The first read starts at current head with no historical replay.
`gap`	PlatformSignalGap
`supported`always	"process.exited" \| "computer.started" \| "computer.stopped" \| "computer.suspended" \| "computer.idle"[]
`retention`always	string

Failures

`404`	Complete scoped discovery proves the computer missing or outside scope.
`429`	The ordinary rate limit or bounded in-flight capacity is exhausted. Capacity refusals include Retry-After.
`501`	A scoped host still holds this computer but lacks signals. Body code is signals_unsupported and reason is unsupported. No active observer fallback.
`503`	Host discovery, scope, protocol validation or the bounded transport is unavailable. Body code is signals_unavailable; keep the prior checkpoint.

GET/computers/{id}/signals