API Reference
The AGENSTAB Engine exposes a high-performance JSON-RPC 2.0 interface over WebSockets. This architecture enables bidirectional communication required for real-time semantic interaction, visual grounding, and Human-in-the-Loop (HITL) workflows.
wss://api.agenstab.com/v1/sessionClient Libraries
AGENSTAB uses standard WebSockets and JSON-RPC 2.0. You don't need proprietary SDKs—just use your language's standard WebSocket library.
Python (websockets)
pip install websockets
Node.js (ws)
npm install ws
Go (gorilla)
go get github.com/gorilla/websocket
Authentication
AGENSTAB uses three layers of authentication depending on the client environment:
Bearer Token
Standard API key in the Authorization header for server-to-server calls.
Subprotocol
WebSocket subprotocol key-<YOUR_API_KEY> for browser environments without header control.
Ephemeral Ticket
Single-use 60-second tickets provisioned via /api/auth/ticket for secure dashboard handoffs.
Lifecycle Methods
Methods for managing isolated browser session contexts.
browser.create_session
Initializes a new isolated browsing context. Returns a session_id. All subsequent calls on this WebSocket will target this session.
Parameters
- token_ttl: integer (default: 3600)
- stealth_mode: boolean (default: false)
- domain_allowlist: array of strings
- hitl_transaction_threshold: integer (cents)
{"jsonrpc": "2.0", "method": "browser.create_session", "params": {"stealth_mode": true}, "id": 1}
browser.terminate_session
Closes the browser instance and purges all session data from edge memory.
Interaction
browser.click
Executes a semantic click on the element identified by agent_id.
browser.type
Inputs text into an input field. Params: agent_id, text, clear_first.
browser.scroll
Scrolls the viewport. Params: direction (up/down/left/right), amount (pixels or 'page').
browser.select
Selects an option from a dropdown. Params: agent_id, value.
browser.wait_for
Pauses execution until a condition is met. Params: condition, timeout_ms.
browser.evaluate
Executes arbitrary JavaScript in the page context. Params: script.
browser.screenshot
Captures a base64 screenshot. Params: full_page (bool).
browser.get_audit_log
Retrieves the verifiable execution log for the session.
browser.restore_checkpoint
Rolls back the session state to a previous snapshot.
browser.save_state
Forces an immediate state snapshot (cookies, local storage, DOM).
browser.get_dom
Retrieves the raw HTML DOM. Discouraged in favor of AXTree.
browser.clear_interstitials
Automatically attempts to dismiss popups and cookie banners.
browser.pause
Pauses agent execution. Useful for HITL intervention.
browser.resume
Resumes agent execution after a pause or HITL intercept.
browser.run_agent
Dispatches a sovereign agent. Params: goal, max_steps.
browser.submit_blueprint
Submits a compiled execution graph for deterministic processing.
browser.push_axtree
Ingests an externally generated Accessibility Tree (Extension flow).
system.sessions
Lists all active sessions for the authenticated API key.
system.extension_heartbeat
Keep-alive signal for extension-driven sessions.
browser.click_coordinates
Fires a click event at absolute viewport (x,y) coordinates.
browser.fill_form
Populates multiple fields simultaneously given an object map.
Error Codes
| Code | Name | Description |
|---|---|---|
| -32001 | ELEMENT_NOT_FOUND | Invalid agent_id. |
| -32002 | PERMISSION_DENIED | Blocked by security policy. |
| -32003 | DOMAIN_RESTRICTED | Not in allowlist. |
| -32004 | INTERSTITIAL_BLOCKED | Navigation obstructed by modal/popup. |
| -32005 | SESSION_EXPIRED | Session token has expired. |
| -32006 | RATE_LIMIT_EXCEEDED | 600 APM limit reached. |
| -32007 | NAVIGATION_TIMEOUT | Target site failed to load. |
| -32008 | VLM_GROUNDING_FAILED | Visual model reasoning failed. |
| -32009 | HITL_REQUIRED | Transaction requires human review. |
| -32010 | RESOURCE_QUOTA_EXCEEDED | Tier usage limits reached. |
| -32011 | ACCOUNT_SUSPENDED | Administrative suspension. |
Changelog
v1.1.0 June 1, 2026
Production Hardening & State Management
- Added:
browser.save_stateandbrowser.restore_checkpointmethods for persistent session handling. - Added: Domain allowlisting at the session creation level to prevent agents from navigating to unauthorized URLs.
- Improved:
browser.clear_interstitialsheuristic engine now successfully clears 94% of standard EU cookie consent banners. - Fixed: Edge case where
SESSION_EXPIRED(-32005) was not immediately emitted upon token invalidation.
v1.0.0 May 15, 2026
Initial Release
- Launch: Stable JSON-RPC 2.0 WebSocket protocol.
- Launch: Semantic Interaction primitives (click, type, scroll, select).
- Launch: AXTree observation endpoint for DOM-to-Vector transformations.