JSON-RPC API Overview

RootCause talks to plugins over JSON-RPC 2.0 on the plugin process stdin (requests from host) and stdout (responses and logs from plugin). One JSON object per line; encoding is UTF-8.

TIP

Do not write to stdout except for JSON-RPC messages. Use plugin.log or stderr for diagnostics.

Message format

Request (Host → Plugin)

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method.name",
  "params": { }
}

• id: string or number, used to match the response.
• method: string (e.g. plugin.init, file.analyze).
• params: object or null; may be omitted when empty.

Success response (Plugin → Host)

{
  "jsonrpc": "2.0",
  "id": "same-as-request",
  "result": { }
}

The plugin must send exactly one response per request, with the same id.

Error response (Plugin → Host)

{
  "jsonrpc": "2.0",
  "id": "same-as-request",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": null
  }
}

See Errors for standard and optional codes.

Notification: plugin.log (Plugin → Host only)

Logging is a notification: no id, no response expected.

{
  "jsonrpc": "2.0",
  "method": "plugin.log",
  "params": { "level": "info", "message": "Starting analysis" }
}

Methods by capability

Method	Capability	Direction
plugin.init	(all)	Host → Plugin
plugin.ping	(all)	Host → Plugin
plugin.shutdown	(all)	Host → Plugin
plugin.log	(all)	Plugin → Host (notification)
repo.discover	discover	Host → Plugin
file.transform	transform	Host → Plugin
file.analyze	analyze	Host → Plugin
scan.report	report	Host → Plugin
rules.list	rules	Host → Plugin
rules.get	rules	Host → Plugin

Detailed request/response examples:

• Lifecycle methods — init, ping, shutdown, log
• Discover & transform — repo.discover, file.transform
• Analyze, report & rules — file.analyze, scan.report, rules.list, rules.get

Typical lifecycle

1. Host starts the plugin process and sends plugin.init.
2. Host sends plugin.ping (e.g. for health checks).
3. Depending on capabilities, host sends repo.discover, file.transform, file.analyze, scan.report, rules.list, rules.get as needed.
4. Plugin may send plugin.log at any time (no response).
5. Host sends plugin.shutdown; plugin responds and exits.

All requests must be answered with exactly one response (success or error) with the same id. Messages are newline-delimited JSON; each line is one message.

Next steps

• Lifecycle methods — init, ping, shutdown, log with examples
• Discover & transform — repo.discover, file.transform
• Analyze, report & rules — file.analyze, scan.report, rules
• Data types — FileSpec, Finding
• Errors — error codes and response format
• Verification — SAST codebase references