Skip to main content

API Reference

Every Karate Agent capability is available via REST endpoints. If your tool can curl, it can drive a browser.

Session Endpoints​

Create Session​

POST /api/sessions
Content-Type: application/json

{}

Returns: {"sessionId": "abc123", "status": "running", ...}

List Sessions​

GET /api/sessions

Get Session​

GET /api/sessions/{sessionId}

Delete Session​

DELETE /api/sessions/{sessionId}

Proxy Endpoint​

Send JavaScript to a running session:

POST /sessions/{sessionId}/proxy
Content-Type: application/json

{"js": "agent.look()"}

Returns the result of the JS execution as JSON.

Autonomous Session Endpoints​

Create Autonomous Session​

POST /api/sessions
Content-Type: application/json

{
  "mode": "auto",
  "prompt": "Task description for the LLM",
  "flowFiles": ["app/login.js", "app/task.md"],
  "model": "openrouter/anthropic/claude-sonnet-4-6",
  "maxIterations": 25
}

Both .js flow files and .md task files can be attached. Task files are inlined into the system prompt; flow files are listed as callable via Flow.run().

Create and Wait (Synchronous)​

POST /api/sessions/run

Same body as above, plus optional "waitTimeout": 300 (seconds). Blocks until the session completes or times out. Returns the final session state.

Get Session Status​

GET /api/sessions/{sessionId}

Download Artifacts​

GET /api/sessions/{sessionId}/download

Returns a zip archive with transcript, report, screenshots, and optional video.

Prompt Endpoint​

GET /sessions/{sessionId}/prompt

Returns a self-contained API reference document that LLMs can read on-the-fly. Point your agent at this URL for contextual documentation.

MCP Endpoint​

POST /mcp

Model Context Protocol server with Streamable HTTP transport. Single karate_eval tool.

# Add to Claude Code
claude mcp add karate http://localhost:4444/mcp

Agent JS API​

These functions are available inside the proxy endpoint's js parameter:

agent.go(url)​

Navigate to a URL.

agent.go('https://example.com')

agent.look()​

Discover actionable elements on the page. Returns structured JSON with {role, name, locator, actions} per element.

agent.look()
// Returns: { elements: [{role: "button", name: "Submit", locator: "{button}Submit", actions: ["click"]}, ...] }

After the first call, subsequent look() calls return diffs only (added, removed, changed, unchanged).

agent.act(locator, action, value?)​

Interact with an element using display-text locators.

agent.act('{button}Submit', 'click')
agent.act('{input}Email', 'input', 'user@example.com')
agent.act('{select}Country', 'select', 'United States')

agent.wait(condition)​

Wait for a condition to be met.

agent.wait('navigation')    // Wait for page navigation
agent.wait('{button}Submit') // Wait for element to appear

match(actual, expected)​

Karate's structural matching with schema markers.

match(result, { ok: true })
match(result.name, '#string')
match(result.count, '#number')

Flow.run(path, args?)​

Execute a flow file at native speed.

Flow.run('app/login', { username: 'admin', password: 'secret' })

File.write(path, content)​

Write a file (used to create flows interactively).

File.write('flows/app/login.js', 'function(args) { ... }')
On This Page