IPC Protocol

KiCad provides a gRPC-based API server that allows external applications to communicate with KiCad using Protocol Buffers. This enables programmatic control of KiCad from other languages and tools.

Overview

The KiCad API uses Protocol Buffers (protobuf) for message serialization and follows a request-response pattern. All API calls are wrapped in an envelope structure that provides status codes and error handling.

Connection

The API server runs on a local socket and uses protobuf messages for communication. Each request must be wrapped in an ApiRequest envelope and will receive an ApiResponse envelope.

Message Envelope

ApiRequest

All requests to KiCad must be wrapped in this envelope:

message ApiRequest {
  ApiRequestHeader header = 1;
  google.protobuf.Any message = 2;
}

Fields:

header - Request metadata (see ApiRequestHeader)
message - The actual command message (type-encoded using protobuf Any)

ApiRequestHeader

message ApiRequestHeader {
  string kicad_token = 1;
  string client_name = 2;
}

Fields:

kicad_token - Opaque string to verify connection to same KiCad instance
client_name - Unique identifier for your client (e.g., “com.example.my_plugin-12345”)

ApiResponse

All responses from KiCad are wrapped in this envelope:

message ApiResponse {
  ApiResponseHeader header = 1;
  ApiResponseStatus status = 2;
  google.protobuf.Any message = 3;
}

Fields:

header - Response metadata
status - Status code and error information
message - The response data (if successful)

ApiResponseStatus

message ApiResponseStatus {
  ApiStatusCode status = 1;
  string error_message = 2;
}

Status Codes

enum ApiStatusCode {
  AS_UNKNOWN = 0;        // Unknown status
  AS_OK = 1;             // Request succeeded
  AS_TIMEOUT = 2;        // Request timed out
  AS_BAD_REQUEST = 3;    // Invalid parameters
  AS_NOT_READY = 4;      // KiCad still starting up
  AS_UNHANDLED = 5;      // Request not handled
  AS_TOKEN_MISMATCH = 6; // kicad_token mismatch
  AS_BUSY = 7;           // KiCad busy with operation
  AS_UNIMPLEMENTED = 8;  // API call not yet implemented
}

Common Commands

Base Commands

GetVersion

Retrieves the KiCad version.

message GetVersion {}

message GetVersionResponse {
  kiapi.common.types.KiCadVersion version = 1;
}

Ping

Checks if the connection is active.

message Ping {}

Returns Empty message with AS_OK status.

GetTextExtents

Calculates the bounding box for text.

message GetTextExtents {
  kiapi.common.types.Text text = 1;
}

Returns kiapi.common.types.Box2 with text bounds.

GetPluginSettingsPath

Gets a writable path for plugin data storage.

message GetPluginSettingsPath {
  string identifier = 1;
}

message StringResponse {
  string response = 1;
}

Board Commands

All board commands are in the kiapi.board.commands package.

Board Stackup

GetBoardStackup

message GetBoardStackup {
  kiapi.common.types.DocumentSpecifier board = 1;
}

message BoardStackupResponse {
  kiapi.board.BoardStackup stackup = 1;
}

GetBoardEnabledLayers

message GetBoardEnabledLayers {
  kiapi.common.types.DocumentSpecifier board = 1;
}

message BoardEnabledLayersResponse {
  uint32 copper_layer_count = 1;
  repeated kiapi.board.types.BoardLayer layers = 2;
}

SetBoardEnabledLayers

Warning: This operation deletes content on disabled layers and cannot be undone.

message SetBoardEnabledLayers {
  kiapi.common.types.DocumentSpecifier board = 1;
  uint32 copper_layer_count = 2;
  repeated kiapi.board.types.BoardLayer layers = 3;
}

Board Origins

GetBoardOrigin

enum BoardOriginType {
  BOT_UNKNOWN = 0;
  BOT_GRID = 1;
  BOT_DRILL = 2;
}

message GetBoardOrigin {
  kiapi.common.types.DocumentSpecifier board = 1;
  BoardOriginType type = 2;
}

Returns Vector2 with the origin coordinates.

SetBoardOrigin

message SetBoardOrigin {
  kiapi.common.types.DocumentSpecifier board = 1;
  BoardOriginType type = 2;
  kiapi.common.types.Vector2 origin = 3;
}

Net Management

GetNets

Retrieves all nets or filtered by netclass.

message GetNets {
  kiapi.common.types.DocumentSpecifier board = 1;
  repeated string netclass_filter = 2;
}

message NetsResponse {
  repeated kiapi.board.types.Net nets = 1;
}

GetItemsByNet

Retrieves copper items belonging to specific nets.

message GetItemsByNet {
  kiapi.common.types.ItemHeader header = 1;
  repeated kiapi.common.types.KiCadObjectType types = 2;
  repeated kiapi.board.types.NetCode net_codes = 3;
}

Returns GetItemsResponse.

GetNetClassForNets

Retrieves the effective netclass for nets (merged from multiple classes).

message GetNetClassForNets {
  repeated kiapi.board.types.Net net = 1;
}

message NetClassForNetsResponse {
  map<string, kiapi.common.project.NetClass> classes = 1;
}

Zone Operations

RefillZones

Blocking operation - KiCad returns AS_BUSY until complete.

message RefillZones {
  kiapi.common.types.DocumentSpecifier board = 1;
  repeated kiapi.common.types.KIID zones = 2;  // Empty = refill all
}

Pad Utilities

GetPadShapeAsPolygon

Computes polygon representation of pad shapes.

message GetPadShapeAsPolygon {
  kiapi.common.types.DocumentSpecifier board = 1;
  repeated kiapi.common.types.KIID pads = 2;
  kiapi.board.types.BoardLayer layer = 3;
}

message PadShapeAsPolygonResponse {
  repeated kiapi.common.types.KIID pads = 1;
  repeated kiapi.common.types.PolygonWithHoles polygons = 2;
}

CheckPadstackPresenceOnLayers

Tests if pads/vias have content on specific layers.

message CheckPadstackPresenceOnLayers {
  kiapi.common.types.DocumentSpecifier board = 1;
  repeated kiapi.common.types.KIID items = 2;
  repeated kiapi.board.types.BoardLayer layers = 3;
}

message PadstackPresenceResponse {
  repeated PadstackPresenceEntry entries = 1;
}

message PadstackPresenceEntry {
  kiapi.common.types.KIID item = 1;
  kiapi.board.types.BoardLayer layer = 2;
  PadstackPresence presence = 3;
}

enum PadstackPresence {
  PSP_UNKNOWN = 0;
  PSP_PRESENT = 1;      // Padstack has shape (is flashed)
  PSP_NOT_PRESENT = 2;  // No shape (not flashed)
}

DRC Markers

InjectDrcError

Creates a DRC marker programmatically (available since v10.0).

enum DrcSeverity {
  DRS_UNKNOWN = 0;
  DRS_WARNING = 1;
  DRS_ERROR = 2;
  DRS_EXCLUSION = 3;
  DRS_IGNORE = 4;
  DRS_INFO = 5;
  DRS_ACTION = 6;
  DRS_DEBUG = 7;
  DRS_UNDEFINED = 8;
}

message InjectDrcError {
  kiapi.common.types.DocumentSpecifier board = 1;
  DrcSeverity severity = 2;
  string message = 3;
  kiapi.common.types.Vector2 position = 4;
  repeated kiapi.common.types.KIID items = 5;
}

message InjectDrcErrorResponse {
  kiapi.common.types.KIID marker = 1;
}

PCB Editor Display

GetVisibleLayers / SetVisibleLayers

message GetVisibleLayers {
  kiapi.common.types.DocumentSpecifier board = 1;
}

message BoardLayers {
  repeated kiapi.board.types.BoardLayer layers = 1;
}

message SetVisibleLayers {
  kiapi.common.types.DocumentSpecifier board = 1;
  repeated kiapi.board.types.BoardLayer layers = 2;
}

GetActiveLayer / SetActiveLayer

message GetActiveLayer {
  kiapi.common.types.DocumentSpecifier board = 1;
}

message BoardLayerResponse {
  kiapi.board.types.BoardLayer layer = 1;
}

message SetActiveLayer {
  kiapi.common.types.DocumentSpecifier board = 1;
  kiapi.board.types.BoardLayer layer = 2;
}

Board Appearance Settings

enum InactiveLayerDisplayMode {
  ILDM_UNKNOWN = 0;
  ILDM_NORMAL = 1;   // Inactive layers shown
  ILDM_DIMMED = 2;   // Inactive layers dimmed
  ILDM_HIDDEN = 3;   // Inactive layers hidden
}

enum NetColorDisplayMode {
  NCDM_UNKNOWN = 0;
  NCDM_ALL = 1;      // Colors on ratsnest and copper
  NCDM_RATSNEST = 2; // Colors on ratsnest only
  NCDM_OFF = 3;      // No net colors
}

enum BoardFlipMode {
  BFM_UNKNOWN = 0;
  BFM_NORMAL = 1;     // Normal view
  BFM_FLIPPED_X = 2;  // Flipped around X axis
}

message BoardEditorAppearanceSettings {
  InactiveLayerDisplayMode inactive_layer_display = 1;
  NetColorDisplayMode net_color_display = 2;
  BoardFlipMode board_flip = 3;
  RatsnestDisplayMode ratsnest_display = 4;
}

message GetBoardEditorAppearanceSettings {}

message SetBoardEditorAppearanceSettings {
  BoardEditorAppearanceSettings settings = 1;
}

Interactive Commands

These commands begin interactive operations in the editor and return immediately, but KiCad becomes busy until the user completes the operation.

InteractiveMoveItems

Note: Takes ownership of the active commit. The move tool will push the commit when confirmed or roll back if cancelled.

message InteractiveMoveItems {
  kiapi.common.types.DocumentSpecifier board = 1;
  repeated kiapi.common.types.KIID items = 2;
}

Error Handling

Always check the status field in ApiResponse:

# Pseudocode example
response = send_api_request(request)

if response.status.status == AS_OK:
    # Process response.message
    pass
elif response.status.status == AS_BUSY:
    # KiCad is busy, retry later
    time.sleep(0.5)
elif response.status.status == AS_BAD_REQUEST:
    # Invalid request parameters
    print(f"Error: {response.status.error_message}")

Best Practices

Set client_name - Always provide a unique client identifier in the request header
Handle AS_BUSY - Some operations are blocking; poll until KiCad is ready
Check status codes - Always verify the response status before accessing message data
Use kicad_token - For long-running clients, use tokens to ensure connection stability
Batch operations - When possible, batch multiple item queries in a single request

Proto File Locations

The protocol buffer definitions are located in the KiCad source tree:

api/proto/common/ - Common types and base commands
api/proto/board/ - PCB board-specific commands
api/proto/schematic/ - Schematic-specific commands

​Overview

​Connection

​Message Envelope

​ApiRequest

​ApiRequestHeader

​ApiResponse

​ApiResponseStatus

​Status Codes

​Common Commands

​Base Commands

​GetVersion

​Ping

​GetTextExtents

​GetPluginSettingsPath

​Board Commands

​Board Stackup

​GetBoardStackup

​GetBoardEnabledLayers

​SetBoardEnabledLayers

​Board Origins

​GetBoardOrigin

​SetBoardOrigin

​Net Management

​GetNets

​GetItemsByNet

​GetNetClassForNets

​Zone Operations

​RefillZones

​Pad Utilities

​GetPadShapeAsPolygon

​CheckPadstackPresenceOnLayers

​DRC Markers

​InjectDrcError

​PCB Editor Display

​GetVisibleLayers / SetVisibleLayers

​GetActiveLayer / SetActiveLayer

​Board Appearance Settings

​Interactive Commands

​InteractiveMoveItems

​Error Handling

​Best Practices

​Proto File Locations

​See Also

Overview

Connection

Message Envelope

ApiRequest

ApiRequestHeader

ApiResponse

ApiResponseStatus

Status Codes

Common Commands

Base Commands

GetVersion

Ping

GetTextExtents

GetPluginSettingsPath

Board Commands

Board Stackup

GetBoardStackup

GetBoardEnabledLayers

SetBoardEnabledLayers

Board Origins

GetBoardOrigin

SetBoardOrigin

Net Management

GetNets

GetItemsByNet

GetNetClassForNets

Zone Operations

RefillZones

Pad Utilities

GetPadShapeAsPolygon

CheckPadstackPresenceOnLayers

DRC Markers

InjectDrcError

PCB Editor Display

GetVisibleLayers / SetVisibleLayers

GetActiveLayer / SetActiveLayer

Board Appearance Settings

Interactive Commands

InteractiveMoveItems

Error Handling

Best Practices

Proto File Locations

See Also