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

{"mode": "repl"}

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.

Job Endpoints

Submit Job

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

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

Get Job Status

GET /api/jobs/{jobId}

Download Report

GET /api/jobs/{jobId}/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) { ... }')