Plugin gRPC API

gRPC interface for external QNTX domain plugins.

Proto file: plugin/grpc/protocol/domain.proto

Service Methods

Method	Request	Response	Streaming
Metadata	Empty	MetadataResponse	No
Initialize	InitializeRequest	InitializeResponse	No
Shutdown	Empty	Empty	No
HandleHTTP	HTTPRequest	HTTPResponse	No
HandleWebSocket	WebSocketMessage	WebSocketMessage	Bidirectional
Health	Empty	HealthResponse	No
ConfigSchema	Empty	ConfigSchemaResponse	No
RegisterGlyphs	Empty	GlyphDefResponse	No
ExecuteJob	ExecuteJobRequest	ExecuteJobResponse	No

Metadata

Metadata returns plugin metadata

Request: Empty
Response: MetadataResponse

Initialize

Initialize initializes the plugin

Request: InitializeRequest
Response: InitializeResponse

Shutdown

Shutdown shuts down the plugin

Request: Empty
Response: Empty

HandleHTTP

HandleHTTP handles an HTTP request

Request: HTTPRequest
Response: HTTPResponse

HandleWebSocket

HandleWebSocket handles a WebSocket connection (bidirectional streaming)

Request: WebSocketMessage
Response: WebSocketMessage
Streaming: bidi

Health

Health checks plugin health

Request: Empty
Response: HealthResponse

ConfigSchema

ConfigSchema returns the configuration schema for this plugin

Request: Empty
Response: ConfigSchemaResponse

RegisterGlyphs

RegisterGlyphs returns custom glyph type definitions provided by this plugin

Request: Empty
Response: GlyphDefResponse

ExecuteJob

ExecuteJob executes an async job Used by Pulse to route jobs to plugin-registered handlers

Request: ExecuteJobRequest
Response: ExecuteJobResponse

Message Types

MetadataResponse

Field	Type	Description
name	string	-
version	string	-
qntx_version	string	-
description	string	-
author	string	-
license	string	-

InitializeRequest

Field	Type	Description
ats_store_endpoint	string	Service endpoints the plugin can call back to QNTX core Format: "host:port" for TCP (e.g., "localhost:50051") Note: Database access is not provided - database is a hard boundary. Plugins should use attestations via ats_store_endpoint instead. ats_store_endpoint: gRPC endpoint for ATSStoreService Provides: Attestation creation, querying, and management
queue_endpoint	string	queue_endpoint: gRPC endpoint for QueueService Provides: Async job enqueue, status, and management
auth_token	string	auth_token: Simple token for authenticating with service endpoints Plugins must include this token in all service RPC calls
config	map<string, string>	Plugin-specific configuration values Simple types (string, int, bool) passed as string representations Complex types (maps, slices) JSON-encoded as strings Plugins should parse and validate values appropriate to their schema

HTTPRequest

Field	Type	Description
method	string	-
path	string	-
headers	HTTPHeader	-
body	bytes	-

HTTPResponse

Field	Type	Description
status_code	int32	-
headers	HTTPHeader	-
body	bytes	-

HTTPHeader

HTTPHeader represents an HTTP header with support for multiple values. HTTP headers can have multiple values (e.g., Set-Cookie, Accept).

Field	Type	Description
name	string	-
values	string	-

WebSocketMessage

HealthResponse

Field	Type	Description
healthy	bool	-
message	string	-
details	map<string, string>	-

ConfigSchemaResponse

Field	Type	Description
fields	map<string, ConfigFieldSchema>	Map of config field name to schema definition

ConfigFieldSchema

Field	Type	Description
type	string	Field type: "string", "number", "boolean", "array"
description	string	Human-readable description of what this field does
default_value	string	Default value (as string representation)
required	bool	Whether this field is required
min_value	string	For number types: minimum value (optional)
max_value	string	For number types: maximum value (optional)
pattern	string	For string types: validation pattern (regex, optional)
element_type	string	For array types: element type (optional)

ScheduleInfo

ScheduleInfo describes a schedule that a plugin wants QNTX to create

Field	Type	Description
handler_name	string	-
interval_seconds	int32	-
enabled_by_default	bool	-
description	string	-
ats_code	string	-

InitializeResponse

InitializeResponse is returned by Initialize RPC

Field	Type	Description
handler_names	string	Handler names this plugin can execute Examples: ["python.script", "python.webhook", "ixgest.git"] Empty list means plugin provides no async handlers (backward compatible)
schedules	ScheduleInfo	Schedules this plugin wants QNTX to create QNTX will auto-create schedule.Job entries for these

ExecuteJobRequest

ExecuteJobRequest is sent to plugins to execute an async job

Field	Type	Description
job_id	string	-
handler_name	string	-
payload	bytes	-
timeout_secs	int64	-

ExecuteJobResponse

ExecuteJobResponse is returned after job execution

Field	Type	Description
success	bool	-
error	string	-
result	bytes	-
progress_current	int32	Progress tracking (optional) - Pulse updates job.Progress
progress_total	int32	-
cost_actual	double	Cost tracking (optional) - Pulse updates job.CostActual
log_entries	JobLogEntry	Execution logs — written to task_logs table by PluginProxyHandler
plugin_version	string	Plugin version that produced this result (e.g., "0.2.14")

JobLogEntry

JobLogEntry is a single log line from plugin job execution

Field	Type	Description
timestamp	string	-
level	string	-
message	string	-
stage	string	-
metadata	string	-

GlyphDefResponse

GlyphDefResponse contains custom glyph type definitions from a plugin

Field	Type	Description
glyphs	GlyphDef	-

GlyphDef

GlyphDef defines a custom glyph type provided by a plugin

Field	Type	Description
symbol	string	Symbol is the glyph identifier (e.g., "⚗" for a chemistry plugin)
title	string	Title is the human-readable name shown in the title bar
label	string	Label is a short identifier for logs and the spawn menu
content_path	string	ContentPath is the HTTP path (relative to /api/{plugin}/) that returns the HTML fragment for this glyph's content area
css_path	string	CSSPath is an optional HTTP path to a stylesheet for this glyph type
default_width	int32	DefaultWidth and DefaultHeight in pixels (0 = use system default)
default_height	int32	-

← Back to API Index