quern-api

Imported from quern-dev/quern (skills/quern-api/SKILL.md). Install upstream with npx skills add quern-dev/quern --skill quern-api. Copyright stays with the author.

Quern REST API Reference

The Quern debug server exposes a REST API at http://localhost:9100. MCP tool names differ from REST paths in non-obvious ways — this reference gives you the correct mappings.

Critical Rules

1. All paths start with /api/v1/ — never omit the prefix
2. Hyphens, not underscores in URL paths: tap-element, open-url, wait-for-element
3. type_text is /device/ui/type — NOT /device/ui/type-text
4. /devices/ (plural) for resolve/ensure — /device/ (singular) for everything else
5. Mocks use /proxy/mocks (plural) — not /proxy/mock
6. Auth: X-API-Key header — read the value from ~/.quern/state.json field api_key
7. Device targeting: most endpoints accept udid as a query param (GET) or body field (POST)

MCP Tool → REST Endpoint Mapping

Device UI

Device App

Device App State / Plist

Device Control

Device Drivers (WDA)

Device Resolution (note: plural /devices/)

Logging

Proxy / Network

Proxy Mocking (plural /mocks)

Proxy Intercept

Proxy Bypass

Proxy Certificates

Capture Sessions

Builds / Crashes

MCP-Only Tools (no REST equivalent)

These tools exist only in the MCP interface and have no REST endpoint:

• ensure_server — checks/restarts the quern server process
• init_app_knowledge — initializes app knowledge base from bundled data
• tail_logs — convenience wrapper; use GET /api/v1/logs/query?tail=true instead

Request Body Schemas

For the full request/response schemas of any endpoint, fetch the OpenAPI spec:

curl http://localhost:9100/openapi.json

For commonly-used endpoint schemas, see references/schemas.md.

Python Helper Pattern

import json, requests

def quern(method, path, **kwargs):
    """Helper for calling the Quern REST API."""
    with open(os.path.expanduser("~/.quern/state.json")) as f:
        api_key = json.load(f)["api_key"]
    url = f"http://localhost:9100/api/v1{path}"
    headers = {"X-API-Key": api_key}
    if method.upper() == "GET":
        return requests.get(url, headers=headers, params=kwargs)
    return requests.request(method, url, headers=headers, json=kwargs)

Mock Filter Syntax

Mocks use mitmproxy filter expressions. Key operators:

• ~d (domain), ~u (URL substring), ~m (method)
• Combine with &: "~d api.example.com & ~m POST & ~u /v1/login"
• ~p does NOT exist — use ~u for path matching

# Example: mock a POST endpoint
quern("POST", "/proxy/mocks",
      pattern="~d staging.api.groundspeak.com & ~u /v1/users",
      status_code=200, body='{"user": "test"}')