API specification

The OpenAPI spec documents the backend-level raw/* analysis methods plus the system methods health, runtime/status, and capabilities. It's generated from the Kotlin serialization models in analysis-api and stays in sync via automated tests.

For human-readable documentation of every OpenAPI operation — schemas, examples, behavioral notes — see the API reference.

Transport note

Real transport is line-delimited JSON-RPC 2.0 over Unix domain sockets, stdio pipes, or TCP — not HTTP. The OpenAPI spec is a logical projection for docs, client codegen, and schema validation. Batch requests and JSON-RPC notifications aren't supported.

Full command catalog

kast rpc can also route higher-level symbol/* orchestration methods and database/* index methods. The complete RPC command catalog lives in cli-rs/resources/kast-skill/references/commands.json and is packaged by the Rust CLI in cli-rs/.

Use OpenAPI when you need the raw backend schema. Use commands.json when an agent or script needs the complete kast rpc catalog, including symbol/resolve, symbol/rename, and database/metrics.

The embedded catalog below is generated from commands.json so readers can browse the actual JSON-RPC suite directly on this page.

Browse the JSON-RPC suite

This section is generated from cli-rs/resources/kast-skill/references/commands.json so the page exposes the same method catalog used by installed agent skills and kast rpc. It embeds the command families, flow-oriented building blocks, and request fields that callers compose into larger automation flows.

Catalog version: dev. Methods: 31.

Method families

The families below are the top-level namespaces accepted by kast rpc.

Family	Role	Source	Methods
`system`	Runtime readiness, backend state, and capability discovery.	backend	`health` `runtime/status` `runtime/shutdown` `runtime/restart` `capabilities`
`symbol`	Name-based orchestration for agent and script workflows.	backend, sqlite	`symbol/scaffold` `symbol/discover` `symbol/query` `symbol/resolve` `symbol/references` `symbol/callers` `symbol/rename` `symbol/write-and-validate`
`raw`	Position- and file-based backend primitives.	backend	`raw/resolve` `raw/references` `raw/call-hierarchy` `raw/type-hierarchy` `raw/semantic-insertion-point` `raw/diagnostics` `raw/rename` `raw/optimize-imports` `raw/apply-edits` `raw/workspace-refresh` `raw/file-outline` `raw/workspace-symbol` `raw/workspace-search` `raw/workspace-files` `raw/implementations` `raw/code-actions` `raw/completions`
`database`	Rust-owned SQLite source-index queries for metrics and impact views.	sqlite	`database/metrics`

Composition building blocks

Use these groups as a starting point for composing multi-step flows. Each method listed here is validated against the generated catalog.

Block	Use it for	Methods
Check runtime	Confirm the daemon is reachable, ready, and honest about supported work.	`health` `runtime/status` `capabilities`
Choose targets	Query indexed declarations or bounded symbol/text searches before optional workspace file inspection.	`symbol/query` `raw/workspace-symbol` `raw/workspace-search` `raw/workspace-files` `symbol/resolve` `raw/file-outline`
Inspect semantics	Resolve declarations, inspect scopes, and read implementation or completion context.	`raw/resolve` `raw/semantic-insertion-point` `raw/implementations` `raw/code-actions` `raw/completions`
Trace relationships	Move from one declaration to usages, callers, callees, and type relationships.	`symbol/references` `raw/references` `symbol/callers` `raw/call-hierarchy` `raw/type-hierarchy`
Plan changes	Ask Kast to derive edit plans or generation context before mutating files.	`symbol/scaffold` `symbol/rename` `raw/rename` `raw/optimize-imports`
Apply and validate	Write prepared changes, refresh affected workspace state, and re-run diagnostics.	`symbol/write-and-validate` `raw/apply-edits` `raw/workspace-refresh` `raw/diagnostics`
Read the index	Use the Rust source-index reader for coupling, dead-code, search, graph, and impact questions.	`database/metrics`

Command catalog

The table below summarizes every method, its backing source, request shape, response type, and success/failure variants when the method uses a discriminated response envelope.

Method	Family	Source	Summary	Required params	Optional params	Response	Variants
`health`	`system`	backend	Basic health check	none	none	`HealthResponse`	single result
`runtime/status`	`system`	backend	Detailed runtime state including indexing progress	none	none	`RuntimeStatusResponse`	single result
`runtime/shutdown`	`system`	backend	Ask the runtime host to shut down after this response is flushed	none	none	`RuntimeLifecycleResponse`	single result
`runtime/restart`	`system`	backend	Ask the runtime host to restart after this response is flushed	none	none	`RuntimeLifecycleResponse`	single result
`capabilities`	`system`	backend	Advertised read and mutation capabilities	none	none	`BackendCapabilities`	single result
`symbol/scaffold`	`symbol`	backend	Gather structural generation context for a Kotlin file	`targetFile`	`workspaceRoot` `targetSymbol` `mode` `kind`	`KastScaffoldResponse`	`SCAFFOLD_SUCCESS` `SCAFFOLD_FAILURE`
`symbol/discover`	`symbol`	backend	Rank candidate declarations for a simple symbol name	`symbol`	`workspaceRoot` `fileHint` `line` `codeSnippet` `kind` `containingType` `maxResults` `includeDeclarationScope`	`KastDiscoverResponse`	`DISCOVER_SUCCESS` `DISCOVER_FAILURE`
`symbol/query`	`symbol`	sqlite	Query compiler-indexed declarations with symbolic hard filters, fielded lexical/name matching, bounded graph relationship evidence, and optional semantic discovery evidence	`query`	`workspaceRoot` `modes` `filters` `anchor` `graph` `semantic` `limit` `includeEvidence` `includeNextRequests`	`KastSymbolQueryResponse`	`SYMBOL_QUERY_SUCCESS` `SYMBOL_QUERY_FAILURE`
`symbol/resolve`	`symbol`	backend	Resolve a symbol by name to its declaration and optional context	`symbol`	`workspaceRoot` `fileHint` `kind` `containingType` `includeDeclarationScope` `includeDocumentation` `surroundingLines` `includeSurroundingMembers`	`KastResolveResponse`	`RESOLVE_SUCCESS` `RESOLVE_FAILURE`
`symbol/references`	`symbol`	backend	Find every usage of a Kotlin symbol	`symbol`	`workspaceRoot` `fileHint` `kind` `containingType` `includeDeclaration`	`KastReferencesResponse`	`REFERENCES_SUCCESS` `REFERENCES_FAILURE`
`symbol/callers`	`symbol`	backend	Expand an incoming or outgoing call hierarchy	`symbol`	`workspaceRoot` `fileHint` `kind` `containingType` `direction` `depth` `maxTotalCalls` `maxChildrenPerNode` `timeoutMillis`	`KastCallersResponse`	`CALLERS_SUCCESS` `CALLERS_FAILURE`
`symbol/rename`	`symbol`	backend	Resolve or target a symbol and apply a rename	`type`	none	`KastRenameResponse`	`RENAME_SUCCESS` `RENAME_FAILURE`
`symbol/write-and-validate`	`symbol`	backend	Apply generated Kotlin code and validate the result	`type`	none	`KastWriteAndValidateResponse`	`WRITE_AND_VALIDATE_SUCCESS` `WRITE_AND_VALIDATE_FAILURE`
`raw/resolve`	`raw`	backend	Resolve the symbol at a file position	`position`	`includeDeclarationScope` `includeDocumentation`	`SymbolResult`	single result
`raw/references`	`raw`	backend	Find all references to the symbol at a file position	`position`	`includeDeclaration` `includeUsageSiteScope`	`ReferencesResult`	single result
`raw/call-hierarchy`	`raw`	backend	Expand a bounded incoming or outgoing call tree	`position` `direction`	`depth` `maxTotalCalls` `maxChildrenPerNode` `timeoutMillis`	`CallHierarchyResult`	single result
`raw/type-hierarchy`	`raw`	backend	Expand supertypes and subtypes from a resolved symbol	`position`	`direction` `depth` `maxResults`	`TypeHierarchyResult`	single result
`raw/semantic-insertion-point`	`raw`	backend	Find the best insertion point for a new declaration	`position` `target`	none	`SemanticInsertionResult`	single result
`raw/diagnostics`	`raw`	backend	Run Kotlin diagnostics on listed files	`filePaths`	none	`DiagnosticsResult`	single result
`raw/rename`	`raw`	backend	Plan a symbol rename by file position	`position` `newName`	`dryRun`	`RenameResult`	single result
`raw/optimize-imports`	`raw`	backend	Optimize imports for one or more files	`filePaths`	none	`ImportOptimizeResult`	single result
`raw/apply-edits`	`raw`	backend	Apply a prepared edit plan with conflict detection	`edits` `fileHashes`	`fileOperations`	`ApplyEditsResult`	single result
`raw/workspace-refresh`	`raw`	backend	Force a targeted or full workspace state refresh	none	`filePaths`	`RefreshResult`	single result
`raw/file-outline`	`raw`	backend	Get a hierarchical symbol outline for a file	`filePath`	none	`FileOutlineResult`	single result
`raw/workspace-symbol`	`raw`	backend	Search the workspace for symbols by name pattern	`pattern`	`kind` `maxResults` `regex` `includeDeclarationScope`	`WorkspaceSymbolResult`	single result
`raw/workspace-search`	`raw`	backend	Search workspace file contents by text or regex	`pattern`	`regex` `maxResults` `fileGlob` `caseSensitive`	`WorkspaceSearchResult`	single result
`raw/workspace-files`	`raw`	backend	List workspace modules and optional file paths	none	`moduleName` `includeFiles` `maxFilesPerModule`	`WorkspaceFilesResult`	single result
`raw/implementations`	`raw`	backend	Find concrete implementations and subclasses for a declaration	`position`	`maxResults`	`ImplementationsResult`	single result
`raw/code-actions`	`raw`	backend	Return available code actions at a file position	`position`	`diagnosticCode`	`CodeActionsResult`	single result
`raw/completions`	`raw`	backend	Return completion candidates available at a file position	`position`	`maxResults` `kindFilter`	`CompletionsResult`	single result
`database/metrics`	`database`	sqlite	Query Rust-owned source-index metrics	`metric`	`workspaceRoot` `limit` `symbol` `depth` `fileGlob` `folderFilter`	`RustMetricsResponse`	`METRICS_SUCCESS` `METRICS_FAILURE`

Command field details

Open a method to inspect the request fields declared in the catalog.

health - Basic health check

No request parameters.

Response type: HealthResponse.

runtime/status - Detailed runtime state including indexing progress

No request parameters.

Response type: RuntimeStatusResponse.

runtime/shutdown - Ask the runtime host to shut down after this response is flushed

No request parameters.

Response type: RuntimeLifecycleResponse.

runtime/restart - Ask the runtime host to restart after this response is flushed

No request parameters.

Response type: RuntimeLifecycleResponse.

capabilities - Advertised read and mutation capabilities

No request parameters.

Response type: BackendCapabilities.

symbol/scaffold - Gather structural generation context for a Kotlin file

Field	Type	Required	Nullable	Values
`workspaceRoot`	`string`	no	yes
`targetFile`	`string`	yes	no
`targetSymbol`	`string`	no	yes
`mode`	`string`	no	no	`implement` `replace` `consolidate` `extract`
`kind`	`string`	no	yes	`class` `interface` `object` `function` `property`

Response type: KastScaffoldResponse. Result variants: SCAFFOLD_SUCCESS, SCAFFOLD_FAILURE.

symbol/discover - Rank candidate declarations for a simple symbol name

Field	Type	Required	Nullable	Values
`workspaceRoot`	`string`	no	yes
`symbol`	`string`	yes	no
`fileHint`	`string`	no	yes
`line`	`integer`	no	yes
`codeSnippet`	`string`	no	yes
`kind`	`string`	no	yes	`class` `interface` `object` `function` `property`
`containingType`	`string`	no	yes
`maxResults`	`integer`	no	no
`includeDeclarationScope`	`boolean`	no	no

Response type: KastDiscoverResponse. Result variants: DISCOVER_SUCCESS, DISCOVER_FAILURE.

Notes:

Use this before symbol/resolve when a simple name is ambiguous or context is available.
Candidates include resolveParams and nextRequest fields that can be sent to symbol/resolve.

symbol/query - Query compiler-indexed declarations with symbolic hard filters, fielded lexical/name matching, bounded graph relationship evidence, and optional semantic discovery evidence

Field	Type	Required	Nullable
`workspaceRoot`	`string`	no	yes
`query`	`string`	yes	no
`modes`	`array of {'type': 'string', 'enum': ['exact', 'lexical', 'structural', 'graph', 'semantic']}`	no	no
`filters`	`object`	no	no
`anchor`	`object`	no	no
`graph`	`object`	no	no
`semantic`	`object`	no	no
`limit`	`integer`	no	no
`includeEvidence`	`boolean`	no	no
`includeNextRequests`	`boolean`	no	no

Response type: KastSymbolQueryResponse. Result variants: SYMBOL_QUERY_SUCCESS, SYMBOL_QUERY_FAILURE.

Notes:

Handled by the Rust CLI before daemon passthrough; JVM backends do not read this SQLite surface.
Hard filters are enforced by SQLite/compiler facts, never by semantic score.
Nested filters include gradleProject, relativePathPrefix, productionOnly, excludePatterns, and usageFacets.
usageFacets is the supported public filter for computed declaration facets; symbol/query does not expose clusterKinds.
Token matching is computed by the Rust CLI from query text and indexed declaration fields without persisted token tables.
Graph depth defaults to 1 and is capped at 2 in the first implementation.
Semantic discovery is represented in the response shape but reports available=false until a sidecar exists.

symbol/resolve - Resolve a symbol by name to its declaration and optional context

Field	Type	Required	Nullable	Values
`workspaceRoot`	`string`	no	yes
`symbol`	`string`	yes	no
`fileHint`	`string`	no	yes
`kind`	`string`	no	yes	`class` `interface` `object` `function` `property`
`containingType`	`string`	no	yes
`includeDeclarationScope`	`boolean`	no	no
`includeDocumentation`	`boolean`	no	no
`surroundingLines`	`integer`	no	yes
`includeSurroundingMembers`	`boolean`	no	no

Response type: KastResolveResponse. Result variants: RESOLVE_SUCCESS, RESOLVE_FAILURE.

Notes:

The 'symbol' field takes simple names only (e.g. 'key'), never fully-qualified names.
Use 'containingType' for scoping and 'fileHint' for disambiguation.
Set includeDeclarationScope, includeDocumentation, surroundingLines, or includeSurroundingMembers only when the extra context is needed.

symbol/references - Find every usage of a Kotlin symbol

Field	Type	Required	Nullable	Values
`workspaceRoot`	`string`	no	yes
`symbol`	`string`	yes	no
`fileHint`	`string`	no	yes
`kind`	`string`	no	yes	`class` `interface` `object` `function` `property`
`containingType`	`string`	no	yes
`includeDeclaration`	`boolean`	no	no

Response type: KastReferencesResponse. Result variants: REFERENCES_SUCCESS, REFERENCES_FAILURE.

Notes:

The 'symbol' field takes simple names only.
Resolve ambiguous names first with 'kind', 'containingType', or 'fileHint'.

symbol/callers - Expand an incoming or outgoing call hierarchy

Field	Type	Required	Nullable	Values
`workspaceRoot`	`string`	no	yes
`symbol`	`string`	yes	no
`fileHint`	`string`	no	yes
`kind`	`string`	no	yes	`class` `interface` `object` `function` `property`
`containingType`	`string`	no	yes
`direction`	`string`	no	no	`incoming` `outgoing`
`depth`	`integer`	no	no
`maxTotalCalls`	`integer`	no	yes
`maxChildrenPerNode`	`integer`	no	yes
`timeoutMillis`	`integer`	no	yes

Response type: KastCallersResponse. Result variants: CALLERS_SUCCESS, CALLERS_FAILURE.

Notes:

The 'symbol' field takes simple names only.

symbol/rename - Resolve or target a symbol and apply a rename

Field	Type	Required	Nullable	Values
`type`	`string`	yes	no	`RENAME_BY_SYMBOL_REQUEST` `RENAME_BY_OFFSET_REQUEST`

Response type: KastRenameResponse. Result variants: RENAME_SUCCESS, RENAME_FAILURE.

symbol/write-and-validate - Apply generated Kotlin code and validate the result

Field	Type	Required	Nullable	Values
`type`	`string`	yes	no	`CREATE_FILE_REQUEST` `INSERT_AT_OFFSET_REQUEST` `REPLACE_RANGE_REQUEST`

Response type: KastWriteAndValidateResponse. Result variants: WRITE_AND_VALIDATE_SUCCESS, WRITE_AND_VALIDATE_FAILURE.

raw/resolve - Resolve the symbol at a file position

Field	Type	Required	Nullable
`position`	`object`	yes	no
`includeDeclarationScope`	`boolean`	no	no
`includeDocumentation`	`boolean`	no	no

Response type: SymbolResult.

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

Field	Type	Required	Nullable
`position`	`object`	yes	no
`includeDeclaration`	`boolean`	no	no
`includeUsageSiteScope`	`boolean`	no	no

Response type: ReferencesResult.

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

Field	Type	Required	Nullable	Values
`position`	`object`	yes	no
`direction`	`string`	yes	no	`INCOMING` `OUTGOING`
`depth`	`integer`	no	no
`maxTotalCalls`	`integer`	no	no
`maxChildrenPerNode`	`integer`	no	no
`timeoutMillis`	`integer`	no	yes

Response type: CallHierarchyResult.

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

Field	Type	Required	Nullable	Values
`position`	`object`	yes	no
`direction`	`string`	no	no	`SUPERTYPES` `SUBTYPES` `BOTH`
`depth`	`integer`	no	no
`maxResults`	`integer`	no	no

Response type: TypeHierarchyResult.

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

Field	Type	Required	Nullable	Values
`position`	`object`	yes	no
`target`	`string`	yes	no	`CLASS_BODY_START` `CLASS_BODY_END` `FILE_TOP` `FILE_BOTTOM` `AFTER_IMPORTS`

Response type: SemanticInsertionResult.

raw/diagnostics - Run Kotlin diagnostics on listed files

Field	Type	Required	Nullable	Values
`filePaths`	`array of string`	yes	no

Response type: DiagnosticsResult.

raw/rename - Plan a symbol rename by file position

Field	Type	Required	Nullable
`position`	`object`	yes	no
`newName`	`string`	yes	no
`dryRun`	`boolean`	no	no

Response type: RenameResult.

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

Field	Type	Required	Nullable	Values
`filePaths`	`array of string`	yes	no

Response type: ImportOptimizeResult.

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

Field	Type	Required	Nullable
`edits`	`array of object`	yes	no
`fileHashes`	`array of object`	yes	no
`fileOperations`	`array of object`	no	no

Response type: ApplyEditsResult.

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

Field	Type	Required	Nullable	Values
`filePaths`	`array of string`	no	no

Response type: RefreshResult.

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

Field	Type	Required	Nullable	Values
`filePath`	`string`	yes	no

Response type: FileOutlineResult.

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

Field	Type	Required	Nullable	Values
`pattern`	`string`	yes	no
`kind`	`string`	no	yes	`CLASS` `INTERFACE` `OBJECT` `FUNCTION` `PROPERTY` `PARAMETER` `UNKNOWN`
`maxResults`	`integer`	no	no
`regex`	`boolean`	no	no
`includeDeclarationScope`	`boolean`	no	no

Response type: WorkspaceSymbolResult.

raw/workspace-search - Search workspace file contents by text or regex

Field	Type	Required	Nullable
`pattern`	`string`	yes	no
`regex`	`boolean`	no	no
`maxResults`	`integer`	no	no
`fileGlob`	`string`	no	yes
`caseSensitive`	`boolean`	no	no

Response type: WorkspaceSearchResult.

raw/workspace-files - List workspace modules and optional file paths

Field	Type	Required	Nullable
`moduleName`	`string`	no	yes
`includeFiles`	`boolean`	no	no
`maxFilesPerModule`	`integer`	no	yes

Response type: WorkspaceFilesResult.

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

Field	Type	Required	Nullable	Values
`position`	`object`	yes	no
`maxResults`	`integer`	no	no

Response type: ImplementationsResult.

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

Field	Type	Required	Nullable	Values
`position`	`object`	yes	no
`diagnosticCode`	`string`	no	yes

Response type: CodeActionsResult.

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

Field	Type	Required	Nullable
`position`	`object`	yes	no
`maxResults`	`integer`	no	no
`kindFilter`	`array of string`	no	yes

Response type: CompletionsResult.

database/metrics - Query Rust-owned source-index metrics

Field	Type	Required	Nullable	Values
`workspaceRoot`	`string`	no	yes
`metric`	`string`	yes	no	`fanIn` `fanOut` `deadCode` `impact` `coupling` `search` `graph`
`limit`	`integer`	no	no
`symbol`	`string`	no	yes
`depth`	`integer`	no	no
`fileGlob`	`string`	no	yes
`folderFilter`	`string`	no	yes

Response type: RustMetricsResponse. Result variants: METRICS_SUCCESS, METRICS_FAILURE.

Notes:

Handled by the Rust CLI before daemon passthrough; JVM backends do not read this SQLite surface.
Use fanIn, fanOut, deadCode, impact, coupling, search, or graph for the v1 Rust metrics reader.

Capability gating

Read and mutation operations require the daemon to advertise the matching capability via the capabilities method. Each operation in the spec includes an x-kast-required-capability extension naming the required capability enum value (e.g. RESOLVE_SYMBOL, RENAME). System methods have no capability requirement.

raw/apply-edits additionally needs the FILE_OPERATIONS capability when the request carries non-empty fileOperations. This conditional requirement is documented with the x-kast-conditional-capability extension.

View the spec

The generated YAML is checked into docs/openapi.yaml in the repository root and served alongside these docs on GitHub Pages.

View openapi.yaml

Download as build artifact

The OpenAPI spec is published as dist/openapi.yaml alongside the CLI and plugin artifacts when you run ./kast.sh build. You can also generate it directly:

./gradlew :analysis-api:generateOpenApiSpec

Import into tools

Valid OpenAPI 3.1. Import into Swagger UI, Redoc, or Stoplight, or use it for client codegen with openapi-generator. The jsonrpc://localhost server URL is a logical placeholder — configure your client for the real transport.

Schema version

The spec version tracks the analysis API schema version (SCHEMA_VERSION), currently 3. OpenAPI info.version is set to 3.0.0 to reflect this.

For contributors: regenerating the spec

To regenerate the checked-in YAML after changing analysis-api models:

./gradlew :analysis-api:generateOpenApiSpec

The AnalysisOpenApiDocumentTest will fail if the checked-in file drifts from the generated output, ensuring the spec stays in sync with the Kotlin models.