Skip to content

API reference

Complete reference for every JSON-RPC method in the Kast analysis daemon, including input/output schemas, examples, and behavioral notes.

At a glance

5 operations for health checks, runtime status, host lifecycle, and capability discovery. No capability gating required.

health — Basic health check

Returns a lightweight health check confirming the daemon is responsive. Use this before dispatching heavier queries.

No parameters.

Signature Description
status: String Health status string, always "ok" when the daemon is responsive.
backendName: String Identifier of the analysis backend (e.g. "headless" or "idea").
backendVersion: String Version string of the analysis backend.
workspaceRoot: String Absolute path of the workspace root directory.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc '{"jsonrpc":"2.0","method":"health","id":1}' --workspace-root=/path/to/project

{
    "method": "health",
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "status": "ok",
        "backendName": "fake",
        "backendVersion": "0.1.0-test",
        "workspaceRoot": "/workspace",
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}
runtime/status — Detailed runtime state including indexing progress

Returns the full runtime state including indexing progress, backend identity, and workspace root. Use this to verify readiness before running analysis commands.

No parameters.

Signature Description
state: RuntimeState Current runtime state: STARTING, INDEXING, READY, or DEGRADED.
healthy: Boolean True when the daemon is responsive and not in an error state.
active: Boolean True when the daemon has an active workspace session.
indexing: Boolean True when the daemon is currently indexing the workspace.
backendName: String Identifier of the analysis backend.
backendVersion: String Version string of the analysis backend.
workspaceRoot: String Absolute path of the workspace root directory.
message: String? Human-readable status message with additional context.
warnings: List<String> Active warning messages about the runtime environment.
sourceModuleNames: List<String> Names of source modules discovered in the workspace.
dependentModuleNamesBySourceModuleName: Map<String, List<String>> Map from source module name to its dependency module names.
referenceIndexReady: Boolean True when the symbol reference index is fully populated.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc '{"jsonrpc":"2.0","method":"runtime/status","id":1}' --workspace-root=/path/to/project

{
    "method": "runtime/status",
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "state": "READY",
        "healthy": true,
        "active": true,
        "indexing": false,
        "backendName": "fake",
        "backendVersion": "0.1.0-test",
        "workspaceRoot": "/workspace",
        "warnings": [],
        "sourceModuleNames": [],
        "dependentModuleNamesBySourceModuleName": {},
        "referenceIndexReady": false,
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}
runtime/shutdown — Request runtime host shutdown after the response is flushed

Requests that the runtime host shut down the current backend after returning a JSON-RPC response. IDEA hosts stop the plugin backend server and indexer without killing the IDE process; headless daemon process lifecycle is handled by the top-level kast stop command.

No parameters.

Signature Description
accepted: Boolean Lifecycle action accepted by the runtime host.
action: RuntimeLifecycleAction Requested lifecycle action.
backendName: String Identifier of the analysis backend.
backendVersion: String Version string of the analysis backend.
workspaceRoot: String Absolute path of the workspace root directory.
message: String? Human-readable lifecycle status message.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc '{"jsonrpc":"2.0","method":"runtime/shutdown","params":{},"id":1}' --workspace-root=/path/to/project

{
    "method": "runtime/shutdown",
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "accepted": true,
        "action": "SHUTDOWN",
        "backendName": "fake",
        "backendVersion": "0.1.0-test",
        "workspaceRoot": "/workspace",
        "message": "Runtime shutdown accepted; action will run after this response is flushed.",
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The response is flushed before the lifecycle action runs, so callers can observe an accepted request.
  • Hosts without lifecycle support return a capability-not-supported JSON-RPC error.
  • Prefer the top-level kast stop command for operator workflows; it handles stale descriptors and backend-specific cleanup.

Error codes  ·  CAPABILITY_NOT_SUPPORTED

runtime/restart — Request runtime host restart after the response is flushed

Requests that the runtime host rebuild the current backend after returning a JSON-RPC response. IDEA hosts restart the plugin backend server and indexer in the open IDE; headless daemon rebuilds are handled by the top-level kast restart command.

No parameters.

Signature Description
accepted: Boolean Lifecycle action accepted by the runtime host.
action: RuntimeLifecycleAction Requested lifecycle action.
backendName: String Identifier of the analysis backend.
backendVersion: String Version string of the analysis backend.
workspaceRoot: String Absolute path of the workspace root directory.
message: String? Human-readable lifecycle status message.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc '{"jsonrpc":"2.0","method":"runtime/restart","params":{},"id":1}' --workspace-root=/path/to/project

{
    "method": "runtime/restart",
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "accepted": true,
        "action": "RESTART",
        "backendName": "fake",
        "backendVersion": "0.1.0-test",
        "workspaceRoot": "/workspace",
        "message": "Runtime restart accepted; action will run after this response is flushed.",
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The response is flushed before the lifecycle action runs, so callers can observe an accepted request.
  • Hosts without lifecycle support return a capability-not-supported JSON-RPC error.
  • Prefer the top-level kast restart command for operator workflows; it combines the host lifecycle request with readiness waiting.

Error codes  ·  CAPABILITY_NOT_SUPPORTED

capabilities — Advertised read and mutation capabilities

Lists every read and mutation capability the current backend advertises, along with server limits. Query this before calling an operation to confirm it is available.

No parameters.

Signature Description
backendName: String Identifier of the analysis backend.
backendVersion: String Version string of the analysis backend.
workspaceRoot: String Absolute path of the workspace root directory.
readCapabilities: List<ReadCapability> Set of read operations this backend supports.
mutationCapabilities: List<MutationCapability> Set of mutation operations this backend supports.
limits: ServerLimits Server-enforced resource limits.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast capabilities --workspace-root=/path/to/project

{
    "method": "capabilities",
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "backendName": "fake",
        "backendVersion": "0.1.0-test",
        "workspaceRoot": "/workspace",
        "readCapabilities": [
            "RESOLVE_SYMBOL",
            "FIND_REFERENCES",
            "CALL_HIERARCHY",
            "TYPE_HIERARCHY",
            "SEMANTIC_INSERTION_POINT",
            "DIAGNOSTICS",
            "FILE_OUTLINE",
            "WORKSPACE_SYMBOL_SEARCH",
            "WORKSPACE_SEARCH",
            "WORKSPACE_FILES",
            "IMPLEMENTATIONS",
            "CODE_ACTIONS",
            "COMPLETIONS"
        ],
        "mutationCapabilities": [
            "RENAME",
            "APPLY_EDITS",
            "FILE_OPERATIONS",
            "OPTIMIZE_IMPORTS",
            "REFRESH_WORKSPACE"
        ],
        "limits": {
            "maxResults": 100,
            "requestTimeoutMillis": 30000,
            "maxConcurrentRequests": 4,
            "perFileScanBudgetMillis": 5000
        },
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

At a glance

12 read-only operations for querying symbols, references, hierarchies, diagnostics, outlines, and completions.

raw/resolve — Resolve the symbol at a file position

Resolves the symbol at a file position, returning its fully qualified name, kind, location, and optional metadata such as type information and documentation.

Capability  ·  RESOLVE_SYMBOL

Signature Description
position: FilePosition File position identifying the symbol to resolve.
includeDeclarationScope: Boolean When true, populates the declarationScope field on the resolved symbol.
includeDocumentation: Boolean When true, populates the documentation field on the resolved symbol.
Signature Description
symbol: Symbol The resolved symbol at the queried position.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/resolveSymbol-request.json --workspace-root=/path/to/project

{
    "method": "raw/resolve",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 20
        },
        "includeDeclarationScope": false,
        "includeDocumentation": false
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "symbol": {
            "fqName": "sample.greet",
            "kind": "FUNCTION",
            "location": {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 20,
                "endOffset": 25,
                "startLine": 4,
                "startColumn": 13,
                "preview": "greet"
            },
            "returnType": "String",
            "parameters": [
                {
                    "name": "name",
                    "type": "String",
                    "isVararg": false
                }
            ],
            "documentation": "/** Greets the provided name. */",
            "containingDeclaration": "sample"
        },
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The position must be an absolute file path with a zero-based byte offset.
  • If the offset does not land on a symbol, the daemon returns a NOT_FOUND error.
  • Optional fields like declarationScope and documentation are only populated when the corresponding query flags are set.

Error codes  ·  NOT_FOUND

raw/references — Find all references to the symbol at a file position

Finds all references to the symbol at a file position across the workspace. Optionally includes the declaration itself.

Capability  ·  FIND_REFERENCES

Signature Description
position: FilePosition File position identifying the symbol whose references to find.
includeDeclaration: Boolean When true, includes the symbol's own declaration in the results.
includeUsageSiteScope: Boolean When true, includes the nearest enclosing declaration scope for each reference usage site.
Signature Description
declaration: Symbol? The resolved declaration symbol, included when includeDeclaration was set.
references: List<Location> List of source locations where the symbol is referenced.
page: PageInfo? Pagination metadata when results are truncated.
searchScope: SearchScope? Describes the scope and exhaustiveness of the search.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/findReferences-request.json --workspace-root=/path/to/project

{
    "method": "raw/references",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 48
        },
        "includeDeclaration": true,
        "includeUsageSiteScope": false
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "declaration": {
            "fqName": "sample.greet",
            "kind": "FUNCTION",
            "location": {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 20,
                "endOffset": 25,
                "startLine": 4,
                "startColumn": 13,
                "preview": "greet"
            },
            "returnType": "String",
            "parameters": [
                {
                    "name": "name",
                    "type": "String",
                    "isVararg": false
                }
            ],
            "documentation": "/** Greets the provided name. */",
            "containingDeclaration": "sample"
        },
        "references": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 48,
                "endOffset": 53,
                "startLine": 4,
                "startColumn": 13,
                "preview": "greet"
            }
        ],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Results are workspace-scoped — references outside the current workspace are not returned.
  • Set includeDeclaration to true to include the symbol's declaration in the result alongside usage sites.
  • Large result sets are paginated; check the page field for continuation.

Error codes  ·  NOT_FOUND

raw/call-hierarchy — Expand a bounded incoming or outgoing call tree

Expands a bounded incoming or outgoing call tree from a function or method. Use incoming to find callers, outgoing to find callees.

Capability  ·  CALL_HIERARCHY

Signature Description
position: FilePosition File position identifying the function or method to expand.
direction: CallDirection INCOMING for callers or OUTGOING for callees.
depth: Int Maximum tree depth to traverse.
maxTotalCalls: Int Maximum total call nodes to return across the entire tree.
maxChildrenPerNode: Int Maximum direct children per node before truncation.
timeoutMillis: Long? Optional timeout in milliseconds for the traversal.
Signature Description
root: CallNode Root node of the call hierarchy tree.
stats: CallHierarchyStats Traversal statistics including truncation indicators.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/callHierarchy-request.json --workspace-root=/path/to/project

{
    "method": "raw/call-hierarchy",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 48
        },
        "direction": "INCOMING",
        "depth": 1,
        "maxTotalCalls": 16,
        "maxChildrenPerNode": 16
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "root": {
            "symbol": {
                "fqName": "sample.greet",
                "kind": "FUNCTION",
                "location": {
                    "filePath": "/workspace/src/Sample.kt",
                    "startOffset": 20,
                    "endOffset": 25,
                    "startLine": 4,
                    "startColumn": 13,
                    "preview": "greet"
                },
                "returnType": "String",
                "parameters": [
                    {
                        "name": "name",
                        "type": "String",
                        "isVararg": false
                    }
                ],
                "documentation": "/** Greets the provided name. */",
                "containingDeclaration": "sample"
            },
            "children": [
                {
                    "symbol": {
                        "fqName": "sample.caller0",
                        "kind": "FUNCTION",
                        "location": {
                            "filePath": "/workspace/src/Sample.kt",
                            "startOffset": 48,
                            "endOffset": 53,
                            "startLine": 4,
                            "startColumn": 13,
                            "preview": "greet"
                        }
                    },
                    "callSite": {
                        "filePath": "/workspace/src/Sample.kt",
                        "startOffset": 48,
                        "endOffset": 53,
                        "startLine": 4,
                        "startColumn": 13,
                        "preview": "greet"
                    },
                    "children": []
                }
            ]
        },
        "stats": {
            "totalNodes": 2,
            "totalEdges": 1,
            "truncatedNodes": 0,
            "maxDepthReached": 1,
            "timeoutReached": false,
            "maxTotalCallsReached": false,
            "maxChildrenPerNodeReached": false,
            "filesVisited": 1
        },
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Traversal is bounded by depth, maxTotalCalls, and maxChildrenPerNode. The stats object reports whether any bound was reached.
  • Set direction to INCOMING for callers or OUTGOING for callees.
  • Cycles are detected and reported via truncation metadata on the affected node.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/type-hierarchy — Expand supertypes and subtypes from a resolved symbol

Expands supertypes and subtypes from a resolved symbol. Use this to understand inheritance relationships.

Capability  ·  TYPE_HIERARCHY

Signature Description
position: FilePosition File position identifying the class or interface to expand.
direction: TypeHierarchyDirection SUPERTYPES, SUBTYPES, or BOTH.
depth: Int Maximum tree depth to traverse.
maxResults: Int Maximum total nodes to return.
Signature Description
root: TypeHierarchyNode Root node of the type hierarchy tree.
stats: TypeHierarchyStats Traversal statistics including truncation indicators.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/typeHierarchy-request.json --workspace-root=/path/to/project

{
    "method": "raw/type-hierarchy",
    "params": {
        "position": {
            "filePath": "/workspace/src/Types.kt",
            "offset": 45
        },
        "direction": "BOTH",
        "depth": 1,
        "maxResults": 16
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "root": {
            "symbol": {
                "fqName": "sample.FriendlyGreeter",
                "kind": "CLASS",
                "location": {
                    "filePath": "/workspace/src/Types.kt",
                    "startOffset": 45,
                    "endOffset": 60,
                    "startLine": 4,
                    "startColumn": 12,
                    "preview": "open class FriendlyGreeter : Greeter"
                },
                "containingDeclaration": "sample",
                "supertypes": [
                    "sample.Greeter"
                ]
            },
            "children": [
                {
                    "symbol": {
                        "fqName": "sample.Greeter",
                        "kind": "INTERFACE",
                        "location": {
                            "filePath": "/workspace/src/Types.kt",
                            "startOffset": 26,
                            "endOffset": 33,
                            "startLine": 3,
                            "startColumn": 11,
                            "preview": "interface Greeter"
                        },
                        "containingDeclaration": "sample"
                    },
                    "children": []
                },
                {
                    "symbol": {
                        "fqName": "sample.LoudGreeter",
                        "kind": "CLASS",
                        "location": {
                            "filePath": "/workspace/src/Types.kt",
                            "startOffset": 77,
                            "endOffset": 88,
                            "startLine": 5,
                            "startColumn": 7,
                            "preview": "class LoudGreeter : FriendlyGreeter()"
                        },
                        "containingDeclaration": "sample",
                        "supertypes": [
                            "sample.FriendlyGreeter"
                        ]
                    },
                    "children": []
                }
            ]
        },
        "stats": {
            "totalNodes": 3,
            "maxDepthReached": 1,
            "truncated": false
        },
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Set direction to SUPERTYPES, SUBTYPES, or BOTH.
  • Traversal is bounded by depth and maxResults. The stats object reports whether truncation occurred.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/semantic-insertion-point — Find the best insertion point for a new declaration

Finds the best insertion point for a new declaration relative to a file position. Use this to place generated code at a semantically appropriate location.

Capability  ·  SEMANTIC_INSERTION_POINT

Signature Description
position: FilePosition File position near the desired insertion location.
target: SemanticInsertionTarget Where to compute the insertion point relative to the position.
Signature Description
insertionOffset: Int Zero-based byte offset where new code should be inserted.
filePath: String Absolute path of the file containing the insertion point.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/semanticInsertionPoint-request.json --workspace-root=/path/to/project

{
    "method": "raw/semantic-insertion-point",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 0
        },
        "target": "FILE_BOTTOM"
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "insertionOffset": 56,
        "filePath": "/workspace/src/Sample.kt",
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The target field controls where the insertion point is computed: class body start/end, file top/bottom, or after imports.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/diagnostics — Run compilation diagnostics for files

Runs compilation diagnostics for one or more files, returning errors, warnings, and informational messages with precise source locations.

Capability  ·  DIAGNOSTICS

Signature Description
filePaths: List<String> Absolute paths of the files to analyze for diagnostics.
Signature Description
diagnostics: List<Diagnostic> List of compilation diagnostics found in the requested files.
page: PageInfo? Pagination metadata when results are truncated.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/diagnostics-request.json --workspace-root=/path/to/project

{
    "method": "raw/diagnostics",
    "params": {
        "filePaths": [
            "/workspace/src/Sample.kt"
        ]
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "diagnostics": [],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Pass one or more absolute file paths. The daemon analyzes each file and returns all diagnostics sorted by location.
  • Diagnostics reflect the current daemon state. Call raw/workspace-refresh first if files were modified outside the daemon.

Error codes  ·  NOT_FOUND

raw/file-outline — Get a hierarchical symbol outline for a file

Returns a hierarchical symbol outline for a single file, listing all named declarations and their nesting.

Capability  ·  FILE_OUTLINE

Signature Description
filePath: String Absolute path of the file to outline.
Signature Description
symbols: List<OutlineSymbol> Top-level symbols in the file, each containing nested children.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/fileOutline-request.json --workspace-root=/path/to/project

{
    "method": "raw/file-outline",
    "params": {
        "filePath": "/workspace/src/Sample.kt"
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "symbols": [
            {
                "symbol": {
                    "fqName": "sample.greet",
                    "kind": "FUNCTION",
                    "location": {
                        "filePath": "/workspace/src/Sample.kt",
                        "startOffset": 20,
                        "endOffset": 25,
                        "startLine": 4,
                        "startColumn": 13,
                        "preview": "greet"
                    },
                    "returnType": "String",
                    "parameters": [
                        {
                            "name": "name",
                            "type": "String",
                            "isVararg": false
                        }
                    ],
                    "documentation": "/** Greets the provided name. */",
                    "containingDeclaration": "sample"
                },
                "children": []
            }
        ],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The outline includes classes, functions, properties, and other named declarations with their fully qualified names.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/workspace-symbol — Search the workspace for symbols by name pattern

Searches the entire workspace for symbols matching a name pattern. Supports substring matching and optional regex.

Capability  ·  WORKSPACE_SYMBOL_SEARCH

Signature Description
pattern: String Search pattern to match against symbol names.
kind: SymbolKind? Filter results to symbols of this kind only.
maxResults: Int Maximum number of symbols to return.
regex: Boolean When true, treats the pattern as a regular expression.
includeDeclarationScope: Boolean When true, populates the declarationScope field on each matched symbol.
Signature Description
symbols: List<Symbol> Symbols matching the search pattern.
page: PageInfo? Pagination metadata when results are truncated.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/workspaceSymbolSearch-request.json --workspace-root=/path/to/project

{
    "method": "raw/workspace-symbol",
    "params": {
        "pattern": "greet",
        "maxResults": 100,
        "regex": false,
        "includeDeclarationScope": false
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "symbols": [
            {
                "fqName": "sample.greet",
                "kind": "FUNCTION",
                "location": {
                    "filePath": "/workspace/src/Sample.kt",
                    "startOffset": 20,
                    "endOffset": 25,
                    "startLine": 4,
                    "startColumn": 13,
                    "preview": "greet"
                },
                "returnType": "String",
                "parameters": [
                    {
                        "name": "name",
                        "type": "String",
                        "isVararg": false
                    }
                ],
                "documentation": "/** Greets the provided name. */",
                "containingDeclaration": "sample"
            },
            {
                "fqName": "sample.FriendlyGreeter",
                "kind": "CLASS",
                "location": {
                    "filePath": "/workspace/src/Types.kt",
                    "startOffset": 45,
                    "endOffset": 60,
                    "startLine": 4,
                    "startColumn": 12,
                    "preview": "open class FriendlyGreeter : Greeter"
                },
                "containingDeclaration": "sample",
                "supertypes": [
                    "sample.Greeter"
                ]
            },
            {
                "fqName": "sample.Greeter",
                "kind": "INTERFACE",
                "location": {
                    "filePath": "/workspace/src/Types.kt",
                    "startOffset": 26,
                    "endOffset": 33,
                    "startLine": 3,
                    "startColumn": 11,
                    "preview": "interface Greeter"
                },
                "containingDeclaration": "sample"
            },
            {
                "fqName": "sample.LoudGreeter",
                "kind": "CLASS",
                "location": {
                    "filePath": "/workspace/src/Types.kt",
                    "startOffset": 77,
                    "endOffset": 88,
                    "startLine": 5,
                    "startColumn": 7,
                    "preview": "class LoudGreeter : FriendlyGreeter()"
                },
                "containingDeclaration": "sample",
                "supertypes": [
                    "sample.FriendlyGreeter"
                ]
            }
        ],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The search is case-insensitive by default for substring matching.
  • Set regex to true for regular expression patterns.
  • Results are bounded by maxResults. Set kind to filter by symbol type.

Error codes  ·  CAPABILITY_NOT_SUPPORTED

raw/workspace-search — Search workspace file contents for text patterns

Searches workspace file contents for literal text or regex patterns. Use this for Kotlin comments, string literals, and other non-symbol content.

Capability  ·  WORKSPACE_SEARCH

Signature Description
pattern: String Search pattern to match as a substring or regex.
regex: Boolean When true, treats the pattern as a regular expression.
maxResults: Int Maximum number of matches to return.
fileGlob: String? Optional glob that restricts which files are searched.
caseSensitive: Boolean When true, matches text with case sensitivity.
Signature Description
matches: List<SearchMatch> Matched lines with absolute file path, line, column, and preview text.
truncated: Boolean True when the result stopped at maxResults.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/workspaceSearch-request.json --workspace-root=/path/to/project

{
    "method": "raw/workspace-search",
    "params": {
        "pattern": "greet",
        "regex": false,
        "maxResults": 100,
        "caseSensitive": true
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "matches": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "lineNumber": 3,
                "columnNumber": 5,
                "preview": "fun greet() = \"hi\""
            },
            {
                "filePath": "/workspace/src/Sample.kt",
                "lineNumber": 5,
                "columnNumber": 13,
                "preview": "fun use() = greet()"
            }
        ],
        "truncated": false,
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Use fileGlob to narrow the search to specific source sets or file types.
  • Set regex to true for regular expression patterns.
  • caseSensitive applies only to the content matching step.

Error codes  ·  CAPABILITY_NOT_SUPPORTED

raw/workspace-files — List workspace modules and optional source files

Lists workspace modules and optionally source files. Use this as a secondary scope check after bounded symbol or text queries.

Capability  ·  WORKSPACE_FILES

Signature Description
moduleName: String? Filter to a single module by name. Omit to list all modules.
includeFiles: Boolean When true, includes individual file paths for each module.
maxFilesPerModule: Int? Maximum file paths to return per module when includeFiles is true. Omit to use the server maxResults limit.
Signature Description
modules: List<WorkspaceModule> List of workspace modules visible to the daemon.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/workspaceFiles-request.json --workspace-root=/path/to/project

{
    "method": "raw/workspace-files",
    "params": {
        "includeFiles": false
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "modules": [
            {
                "name": "fake-module",
                "sourceRoots": [
                    "/workspace/src"
                ],
                "dependencyModuleNames": [],
                "files": [],
                "filesTruncated": false,
                "fileCount": 2
            }
        ],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Leave includeFiles false for the bounded module summary.
  • When file paths are required, filter by moduleName and set a small maxFilesPerModule.

Error codes  ·  CAPABILITY_NOT_SUPPORTED

raw/implementations — Find concrete implementations and subclasses for a declaration

Finds concrete implementations and subclasses for an interface or abstract class declaration.

Capability  ·  IMPLEMENTATIONS

Signature Description
position: FilePosition File position identifying the interface or abstract class.
maxResults: Int Maximum number of implementation symbols to return.
Signature Description
declaration: Symbol The interface or abstract class symbol that was queried.
implementations: List<Symbol> Concrete implementations or subclasses found.
exhaustive: Boolean True when all implementations were found within maxResults.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/implementations-request.json --workspace-root=/path/to/project

{
    "method": "raw/implementations",
    "params": {
        "position": {
            "filePath": "/workspace/src/Types.kt",
            "offset": 45
        },
        "maxResults": 10
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "declaration": {
            "fqName": "sample.Greeter",
            "kind": "INTERFACE",
            "location": {
                "filePath": "/workspace/src/Types.kt",
                "startOffset": 26,
                "endOffset": 33,
                "startLine": 3,
                "startColumn": 11,
                "preview": "interface Greeter"
            },
            "containingDeclaration": "sample"
        },
        "implementations": [
            {
                "fqName": "sample.LoudGreeter",
                "kind": "CLASS",
                "location": {
                    "filePath": "/workspace/src/Types.kt",
                    "startOffset": 77,
                    "endOffset": 88,
                    "startLine": 5,
                    "startColumn": 7,
                    "preview": "class LoudGreeter : FriendlyGreeter()"
                },
                "containingDeclaration": "sample",
                "supertypes": [
                    "sample.FriendlyGreeter"
                ]
            }
        ],
        "exhaustive": true,
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The position must point to an interface, abstract class, or open class.
  • Results include the exhaustive flag indicating whether all implementations were found within maxResults.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/code-actions — Return available code actions at a file position

Returns available code actions at a file position, such as quick fixes and refactoring suggestions.

Capability  ·  CODE_ACTIONS

Signature Description
position: FilePosition File position to query for available code actions.
diagnosticCode: String? Filter to actions that address this diagnostic code.
Signature Description
actions: List<CodeAction> Available code actions at the queried position.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/codeActions-request.json --workspace-root=/path/to/project

{
    "method": "raw/code-actions",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 0
        }
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "actions": [],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Code actions are context-dependent and may return an empty list when no actions are applicable.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/completions — Return completion candidates available at a file position

Returns completion candidates available at a file position. Use this to discover what symbols, keywords, or snippets the compiler suggests.

Capability  ·  COMPLETIONS

Signature Description
position: FilePosition File position where completions are requested.
maxResults: Int Maximum number of completion items to return.
kindFilter: List<SymbolKind>? Restrict results to these symbol kinds only.
Signature Description
items: List<CompletionItem> Completion candidates available at the queried position.
exhaustive: Boolean True when all candidates were returned within maxResults.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/completions-request.json --workspace-root=/path/to/project

{
    "method": "raw/completions",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 0
        },
        "maxResults": 10
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "items": [
            {
                "name": "greet",
                "fqName": "sample.greet",
                "kind": "FUNCTION",
                "type": "String",
                "parameters": [
                    {
                        "name": "name",
                        "type": "String",
                        "isVararg": false
                    }
                ],
                "documentation": "/** Greets the provided name. */"
            }
        ],
        "exhaustive": true,
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Results are bounded by maxResults. The exhaustive flag indicates whether all candidates were returned.
  • Use kindFilter to restrict results to specific symbol kinds.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

At a glance

4 operations that modify workspace state: rename, optimize imports, apply edits, and refresh.

raw/rename — Plan a symbol rename (dry-run by default)

Plans a symbol rename by computing all text edits needed across the workspace. This is a dry-run by default — it returns edits without applying them.

Capability  ·  RENAME

Signature Description
position: FilePosition File position identifying the symbol to rename.
newName: String The new name to assign to the symbol.
dryRun: Boolean When true (default), computes edits without applying them.
Signature Description
edits: List<TextEdit> Text edits needed to perform the rename across the workspace.
fileHashes: List<FileHash> File hashes at edit-plan time for conflict detection.
affectedFiles: List<String> Absolute paths of all files that would be modified.
searchScope: SearchScope? Describes the scope and exhaustiveness of the rename search.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/rename-request.json --workspace-root=/path/to/project

{
    "method": "raw/rename",
    "params": {
        "position": {
            "filePath": "/workspace/src/Sample.kt",
            "offset": 20
        },
        "newName": "welcome",
        "dryRun": true
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "edits": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 20,
                "endOffset": 25,
                "newText": "welcome"
            },
            {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 48,
                "endOffset": 53,
                "newText": "welcome"
            }
        ],
        "fileHashes": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "hash": "fd31168346a51e49dbb21eca8e5d7cc897afe7116bb3ef21754f782ddb261f72"
            }
        ],
        "affectedFiles": [
            "/workspace/src/Sample.kt"
        ],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • The result includes file hashes for conflict detection when applying edits later.
  • Pair with raw/apply-edits to execute the rename after review.

Error codes  ·  NOT_FOUND

raw/optimize-imports — Optimize imports for one or more files

Optimizes imports for one or more files, removing unused imports and sorting the remainder.

Capability  ·  OPTIMIZE_IMPORTS

Signature Description
filePaths: List<String> Absolute paths of the files whose imports should be optimized.
Signature Description
edits: List<TextEdit> Text edits that remove unused imports and sort the remainder.
fileHashes: List<FileHash> File hashes at edit-plan time for conflict detection.
affectedFiles: List<String> Absolute paths of all files that were modified.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/optimizeImports-request.json --workspace-root=/path/to/project

{
    "method": "raw/optimize-imports",
    "params": {
        "filePaths": [
            "/workspace/src/Sample.kt"
        ]
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "edits": [],
        "fileHashes": [],
        "affectedFiles": [],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Returns the computed edits and file hashes. The daemon applies changes directly.

Error codes  ·  NOT_FOUND, CAPABILITY_NOT_SUPPORTED

raw/apply-edits — Apply a prepared edit plan with conflict detection

Applies a prepared edit plan with file-hash conflict detection. Pass the edits and hashes returned by a prior raw/rename or other planning operation.

Capability  ·  APPLY_EDITS

Signature Description
edits: List<TextEdit> Text edits to apply, typically from a prior rename or code action.
fileHashes: List<FileHash> Expected file hashes for conflict detection before writing.
fileOperations: List<FileOperation> Optional file create or delete operations to perform.
Signature Description
applied: List<TextEdit> Text edits that were successfully applied.
affectedFiles: List<String> Absolute paths of all files that were modified.
createdFiles: List<String> Absolute paths of files created by file operations.
deletedFiles: List<String> Absolute paths of files deleted by file operations.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/applyEdits-request.json --workspace-root=/path/to/project

{
    "method": "raw/apply-edits",
    "params": {
        "edits": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 0,
                "endOffset": 0,
                "newText": "// edited\n"
            }
        ],
        "fileHashes": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "hash": "fd31168346a51e49dbb21eca8e5d7cc897afe7116bb3ef21754f782ddb261f72"
            }
        ],
        "fileOperations": []
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "applied": [
            {
                "filePath": "/workspace/src/Sample.kt",
                "startOffset": 0,
                "endOffset": 0,
                "newText": "// edited\n"
            }
        ],
        "affectedFiles": [
            "/workspace/src/Sample.kt"
        ],
        "createdFiles": [],
        "deletedFiles": [],
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • File hashes are compared before writing. If a file changed since the edits were planned, the operation fails with a conflict error.
  • Supports optional fileOperations for creating or deleting files.

Error codes  ·  CONFLICT, VALIDATION_ERROR

raw/workspace-refresh — Force a targeted or full workspace state refresh

Forces the daemon to refresh its workspace state. Use this after external file modifications to ensure the daemon's view is current.

Capability  ·  REFRESH_WORKSPACE

Signature Description
filePaths: List<String> Absolute paths of files to refresh. Empty for a full workspace refresh.
Signature Description
refreshedFiles: List<String> Absolute paths of files whose state was refreshed.
removedFiles: List<String> Absolute paths of files that were removed from the workspace.
fullRefresh: Boolean True when a full workspace refresh was performed.
schemaVersion: Int Protocol schema version for forward compatibility. 
kast rpc --request-file=docs/examples/refreshWorkspace-request.json --workspace-root=/path/to/project

{
    "method": "raw/workspace-refresh",
    "params": {
        "filePaths": [
            "/workspace/src/Sample.kt"
        ]
    },
    "id": 1,
    "jsonrpc": "2.0"
}

{
    "result": {
        "refreshedFiles": [
            "/workspace/src/Sample.kt"
        ],
        "removedFiles": [],
        "fullRefresh": false,
        "schemaVersion": 3
    },
    "id": 1,
    "jsonrpc": "2.0"
}

Behavioral notes

  • Pass specific file paths for a targeted refresh, or omit for a full workspace refresh.
  • The result reports which files were refreshed and which were removed.

Error codes  ·  CAPABILITY_NOT_SUPPORTED