API Reference

Each section describes one API or workflow. The code selector is shared across the page: choosing a language in one panel updates every panel. Both published SDKs expose this surface — TypeScript with async methods and camelCase options, Python with blocking methods and the same options in snake_case (max_iterations, screenshot_enabled, result_schema, …). Sections and options marked Coming soon ship with a later native runtime release. Attaching to a caller-owned Playwright page remains TypeScript-only.

Go to Sign up and complete the account flow, then open the dashboard. The dashboard is where you manage API keys and account usage.

In the dashboard, open the API keys section, create a key, and copy the secret when it appears. The complete secret is shown only at creation. Anyone who obtains it can authenticate as your account and consume your usage balance. Do not commit it to source control, include it in client-side browser code or a distributed binary, print it in logs, or send it through chat and issue trackers.

export NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>"

Run export in a terminal before starting your application from that same terminal. It sets NODEMANTIS_API_KEY for the current shell process and programs launched by it. It does not upload the key or change Node Mantis configuration, and it disappears when that shell closes.

$env:NODEMANTIS_API_KEY = "sk_live_<copy-from-dashboard>"

PowerShell's $env: assignment has the same current-session scope. Start the application from that PowerShell window. For local Python use, python -m nodemantis configure --api-key "sk_live_<copy-from-dashboard>" can instead write a private user config file.

Node Mantis drives a real Google Chrome on your machine. Managed NodeMantis.start sessions and the default TypeScript preflight require a discoverable Google Chrome installation. The npm package declares Playwright as a peer dependency, so npm installs the Playwright library alongside the SDK — but installing the packages does not download a browser for you, so install Chrome explicitly before your first run.

npm install node-mantis@0.1.0-alpha.10
npx playwright install chrome

python -m pip install "node-mantis[browser]==0.1.0a10"
python -m nodemantis install-browser --browser chrome

npm install -g node-mantis@0.1.0-alpha.10   # or: brew install node-mantis/tap/nodemantis
nodemantis install-browser --browser chrome

The Python [browser] extra installs Playwright for Python smoke and diagnostic tools. A TypeScript application can attach Node Mantis to a caller-owned Chromium page after installing the matching browser binary:

npx playwright install chromium

A missing browser produces an install command instead of downloading in the background. Python smoke runs may offer to install the selected browser when attached to an interactive terminal. Non-interactive and CI runs fail until installation is explicit, or until smoke is invoked with --install-browser.

These options configure NodeMantis.start and NodeMantis.attach. NodeMantis.preflight uses the same apiKey resolution rules. Options are listed in their TypeScript form; Python takes the same options in snake_case (api_key, llm_timeout_ms, default_agent_options, logging).

The native runtime writes an info log by default. Local defaults are seven days and 200 MB, with startup cleanup. Platform directories are ~/Library/Logs/nodemantis on macOS, $XDG_STATE_HOME/nodemantis/logs on Linux when XDG_STATE_HOME is set (otherwise ~/.local/state/nodemantis/logs), and %LOCALAPPDATA%\nodemantis\logs on Windows.

The runtime process is shared. Directory and retention settings are first-start-wins for a running process; a later session can raise the effective level but cannot lower it. The equivalent environment variables are NODEMANTIS_LOG_LEVEL, NODEMANTIS_LOG_DIR, NODEMANTIS_LOG_RETENTION_DAYS, and NODEMANTIS_LOG_MAX_MB. Treat debug logs as sensitive. Hosted service transcripts are covered by the Privacy Policy and may be retained for up to 60 days.

Validates hosted API health, key presence, authenticated account usage, and a browser launch. Run it when preparing a workstation or CI image. Python exposes the same checks as NodeMantis.preflight; run_smoke and python -m nodemantis doctor remain the installation-smoke alternatives.

import { NodeMantis } from "node-mantis";

const report = await NodeMantis.preflight({
  checkBrowser: true,
  timeoutMs: 5000,
});

if (!report.ok) {
  console.error(report.checks);
  process.exit(1);
}

from nodemantis import NodeMantis

report = NodeMantis.preflight(check_browser=True, timeout_ms=5000)

if not report.ok:
    raise SystemExit(report.checks)

nodemantis doctor --browser chrome --json

TypeScript returns { ok, hasApiKey, checks }. Check names are service, apiKey, usage, andbrowser. Its options are listed below.

Launches a managed local Chrome context and returns a Node Mantis session. The session owns the context, so call mantis.close() when work finishes. Pass navigationOnly: true for goand direct read-only page inspection without installing agent perception;run, step, retrieve, extract, and check reject in that mode. It accepts all shared client options plus the browser options below.

const mantis = await NodeMantis.start({
  startUrl: "https://example.com",
  headless: true,
  viewport: { width: 1280, height: 720 },
});

mantis = NodeMantis.start(
    start_url="https://example.com",
    headless=True,
    viewport={"width": 1280, "height": 720},
)

Binds Node Mantis to an existing Playwright Page and accepts the shared client options. The caller retains ownership of the page, context, and browser. mantis.close() ends the Node Mantis session but does not close those caller-owned Playwright resources.

const mantis = await NodeMantis.attach(page);

Navigates the session page and returns the final URL and title as { ok, url, title }. Calls on one session are serialized with all other Node Mantis operations. Direct calls through mantis.page bypass that queue.

const navigation = await mantis.go("https://example.com", {
  waitUntil: "domcontentloaded",
  timeout: 30000,
});

navigation = mantis.go(
    "https://example.com",
    wait_until="domcontentloaded",
    timeout=30000,
)

Runs a multi-step browser goal until it succeeds, fails, times out, or reaches its iteration limit. Pass a schema or enable retrieval to include value, valueStatus, valueContributorIds, and any retrievalError in the operation result.

const result = await mantis.run("Open the pricing page.", {
  maxIterations: 10,
  timeout: 120000,
  screenshotEnabled: true,
});

result = mantis.run(
    "Open the pricing page.",
    max_iterations=10,
    timeout=120000,
    screenshot_enabled=True,
)

nodemantis run "Open the pricing page." \
  --url https://example.com --max-iterations 10 --timeout-ms 120000

Runs a bounded instruction against the current page, maps maxActions to the loop limit, and stops as soon as the visible page satisfies the instruction. Navigation is discouraged unless allowNavigation is true or staying on the page makes the instruction impossible.

const result = await mantis.step("Open the pricing page.", {
  maxActions: 5,
  allowNavigation: true,
});

result = mantis.step(
    "Open the pricing page.",
    max_actions=5,
    allow_navigation=True,
)

Performs one semantic capture of the current live DOM and returns grounded current-page information. It does not click, search, paginate, or navigate. Use retrieval-enabled run or stepwhen interaction is required.

The single-capture behavior and result fields shown here (contributorIds and the three terminal statuses) are the forthcoming native-runtime form. In the published npm alpha, retrieve also accepts a mode (page, interactive, or auto) and can additionally return partial and ambiguous statuses.

const result = await mantis.retrieve("List the plans on this page.", {
  schema: z.object({ plans: z.array(z.string()) }),
  model: "small",
});

if (result.status === "success") {
  console.log(result.data, result.contributorIds);
} else {
  console.log(result.status, result.reason);
}

result = mantis.retrieve(
    "List the plans on this page.",
    schema={
        "type": "object",
        "properties": {"plans": {"type": "array", "items": {"type": "string"}}},
        "required": ["plans"],
    },
    model="small",
)

if result.status == "success":
    print(result.data, result.contributor_ids)
else:
    print(result.status, result.reason)

nodemantis retrieve "List the plans on this page." \
  --url https://example.com --model small \
  --schema '{"type":"object","properties":{"plans":{"type":"array","items":{"type":"string"}}},"required":["plans"]}' \
  --json

Supported schema keywords are type, properties, required, items, enum, minItems, maxItems, and description. Metadata keywords such as $schema,$id, title, default, examples, and additionalProperties are ignored. Unsupported keywords including $ref, anyOf, pattern, and format reject the request with SCHEMA_UNSUPPORTED.

Compatibility API for current-page extraction. It accepts a schema and model, then returns the extracted value through the standard operation result's value field. Use retrieve when the strict terminal status, contributor IDs, warnings, token usage, and final URL are required.

const result = await mantis.extract("Summarize this page.", {
  schema: z.object({ summary: z.string() }),
  model: "small",
});

console.log(result.ok, result.value);

result = mantis.extract(
    "Summarize this page.",
    schema={
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
    },
    model="small",
)

print(result.ok, result.value)

Evaluates whether the current page satisfies a condition using visible page text. It returns the standard operation shape. An ok: false value can be a legitimate negative verdict, not only an execution failure.

const result = await mantis.check(
  "Is the pricing page visible?",
  { model: "small" },
);

result = mantis.check("Is the pricing page visible?", model="small")

Marks the session closed and releases a managed context created by NodeMantis.start. It is idempotent and best-effort aborts active and queued SDK operations. For sessions created by NodeMantis.attach, the caller still owns and closes the Playwright resources.

await mantis.close();

mantis.close()

Resolves Python credentials with a source label, the selected config path, and the parsed file config. It does not make a network request.

from nodemantis import resolve_config

config = resolve_config()

print(config.api_key_source, config.config_path)

Normalizes the current operating system and architecture and returns { os_name, arch, tag }. It raises UnsupportedPlatformError outside the four supported targets.

from nodemantis import runtime_platform_info

platform = runtime_platform_info()
print(platform.os_name, platform.arch, platform.tag)

Executes the Python installation smoke: resolves credentials, checks the supported platform, runs the package compatibility self-check, probes authenticated hosted API usage, launches the selected browser, and asserts the bundled local fixture. This helper is not the browser-driving product runtime.

from nodemantis import run_smoke

result = run_smoke(
    browser="chrome",
)

print(result.ok, result.runtime_platform, result.assertion)

Both distributions install a nodemantis command. The npm package ships the full CLI surface — run and retrieve plus the setup verbs — documented in the CLI reference. The Python package exposes only the setup verbs (configure, doctor, install-browser, smoke) as operational commands. Use --help on any command for its complete argument list.

nodemantis configure --api-key "sk_live_<copy-from-dashboard>"
nodemantis doctor --browser chrome --json
nodemantis run "Open the pricing page and report the Pro plan price." \
  --url https://example.com
nodemantis retrieve "List the plan names." --url https://example.com --json

python -m nodemantis configure --api-key "sk_live_<copy-from-dashboard>"
python -m nodemantis doctor --browser chrome --json
python -m nodemantis install-browser --browser chrome
python -m nodemantis smoke --browser chrome

run, step, extract, and check return an operation result with ok, reason, and optional iterations and traceId. Retrieval-enabled runs also include value, valueStatus, valueContributorIds, and retrievalError.

retrieve returns exactly one terminal status: success, not_found, or error. Every result includes ok, status, data, contributorIds, reason, string warnings, tokens, finalUrl, and an optional traceId. Success has non-null data and at least one contributor ID; not-found is ok: true with null data; error is ok: false with null data.

The session also exposes readonly mantis.page and mantis.sdkSessionId for direct Playwright access and correlation. mantis.capabilityMode arrives with the native runtime.