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. The TypeScript SDK below is available in npm 0.1.0-alpha.6; sections and options marked Coming soon ship with a later native runtime release. Python 0.1.0a1 contains configuration, runtime, and installation-smoke APIs; it does not expose preflight or browser-driving agent sessions.

Account

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

API key

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.

macOS and Linux shell

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.

Windows PowerShell

$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.

Browser installation

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. Installing the package does not download a browser for you, so install Chrome explicitly before your first run.

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

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

The Python [browser] extra installs Playwright for Python smoke and diagnostic tools. Python can explicitly test Playwright Chromium, and a TypeScript application can attach Node Mantis to a caller-owned Chromium page:

npx playwright install chromium

python -m nodemantis install-browser --browser 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.

Shared TypeScript client options

These options configure NodeMantis.start and NodeMantis.attach. NodeMantis.preflight uses the same apiKey resolution rules.

Local logging Coming soon

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.

NodeMantis.preflightAvailable now

Validates hosted API health, key presence, authenticated account usage, and a browser launch. Run it when preparing a TypeScript workstation or CI image. PyPI 0.1.0a1 does not export preflight; use run_smoke or python -m nodemantis doctor for that published package.

import { NodeMantis } from "node-mantis";

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

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

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

NodeMantis.start(options?)Available now

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 },
});

NodeMantis.attach(page, options?)Available now

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);

mantis.go(url, options?)Available now

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,
});

mantis.run(goal, options?)Available now

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,
});

mantis.step(instruction, options?)Available now

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,
});

mantis.retrieve(prompt, options?)Available now

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 npm 0.1.0-alpha.6, 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);
}

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.

mantis.extract(prompt, options?)Available now

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);

mantis.check(prompt, options?)Available now

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" },
);

mantis.close()Available now

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();

resolve_config(...)

Resolves Python credentials with a source label, the selected config path, the hosted endpoint and its source label, 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.backend_url_source, config.config_path)

runtime_platform_info(...)

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)

run_smoke(...)

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)

Python command line

The Python package also exposes the module helpers as operational commands. Use --help on any command for its complete argument list.

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

PyPI 0.1.0a1 also accepts --backend-url on configure, doctor, and smoke. Keep the built-in hosted endpoint unless you operate an approved private environment.

Result contracts

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.