All RuleGo-Server APIs are based on the /api/v1 path and can be authenticated via JWT or API Key (enabled when require_auth = true).

• Full API reference (including request/response examples, error codes, configuration reference): api-reference.md (opens new window)

General Information

Authentication

Authorization: Bearer {jwtToken或apiKey}

or

X-API-Key: {apiKey}

Pagination Parameters

Parameter	Description
page	Page number, starting from 1
size	Items per page

Permission Identifiers

The format is resource:action, such as rule:read, rule:write.

Authentication

Method	Path	Permission	Description
POST	/api/v1/login	None	Login to obtain JWT token

Rule Chain Management

Method	Path	Permission	Description
GET	/api/v1/rules	rule:read	List rule chains
GET	/api/v1/rules/:id	rule:read	Get rule chain DSL
GET	/api/v1/rules/_/latest	rule:read	Get the most recently modified rule chain for the current user
POST	/api/v1/rules/:id	rule:write	Create/update rule chain (auto-loaded after saving)
POST	/api/v1/rules/:id/base	rule:write	Update basic information (name, description, category)
POST	/api/v1/rules/:id/config/:varType	rule:write	Save configuration variables
DELETE	/api/v1/rules/:id	rule:delete	Delete rule chain
POST	/api/v1/rules/:id/operate/:type	rule:operate	Deployment operations (start/stop/set-to-main)

List Rule Chains

GET /api/v1/rules?keywords=&root=&disabled=&category=&page=1&size=20
Authorization: Bearer {token}

Parameter	Type	Description
keywords	string	Keyword filter
root	bool	Filter root rule chains
disabled	bool	Filter disabled rule chains
category	string	Filter by category
page / size	int	Pagination

Create/Update Rule Chain

POST /api/v1/rules/{id}
Authorization: Bearer {token}
Content-Type: application/json

{Rule chain DSL JSON}

Deployment Operations

POST /api/v1/rules/{id}/operate/{operateType}
Authorization: Bearer {token}

operateType	Description
start	Deploy rule chain (start running)
stop	Stop rule chain (undeploy)
set-to-main	Set as main rule chain

Rule Chain DSL Structure

{
  "ruleChain": {
    "id": "myChain",
    "name": "我的规则链",
    "debugMode": false,
    "root": false,
    "disabled": false,
    "additionalInfo": {
      "description": "规则链描述",
      "category": "分类",
      "inputSchema": {},
      "createTime": "2026/01/01 00:00:00"
    }
  },
  "metadata": {
    "endpoints": [],
    "nodes": [
      {
        "id": "node_1",
        "type": "jsFilter",
        "name": "过滤节点",
        "debugMode": false,
        "configuration": { "jsScript": "return msg.age > 18;" },
        "additionalInfo": { "layoutX": 300, "layoutY": 200 }
      }
    ],
    "connections": [
      { "fromId": "node_1", "toId": "node_2", "type": "True" }
    ]
  }
}

additionalInfo Field Descriptions

Field	Description
description	Rule chain description
category	Category identifier
inputSchema	Input parameter JsonSchema (for MCP tools, AI Agent)
createTime / updateTime	Creation/update time
layoutX / layoutY	Editor canvas coordinates (node level only)
username	Owner user

Application Integration Endpoints

After saving a rule chain, the system automatically generates the following endpoints for it:

Endpoint	Description
POST /api/v1/rules/{id}/execute/{msgType}	Synchronous execution
POST /api/v1/rules/{id}/notify/{msgType}	Asynchronous notification
POST /api/v1/rules/{id}/v1/chat/completions	OpenAI-compatible chat

Rule Chain Execution

Method	Path	Permission	Description
POST	/api/v1/rules/:id/execute/:msgType	rule:execute	Synchronous execution
POST	/api/v1/rules/:id/notify/:msgType	rule:execute	Asynchronous notification
POST	/api/v1/rules/:id/v1/chat/completions	rule:execute	OpenAI-compatible chat

Synchronous Execution

POST /api/v1/rules/{id}/execute/{msgType}
Authorization: Bearer {token}
Content-Type: application/json

{ "message": "hello", "metadata": { "key": "value" } }

curl -X POST http://localhost:9090/api/v1/rules/myChain/execute/TEST \
  -H "Content-Type: application/json" \
  -d '{"temperature": 36.5, "deviceId": "sensor001"}'

Asynchronous Notification

Returns immediately after triggering, without waiting for the result. Suitable for scenarios such as log processing and message distribution.

OpenAI-Compatible Chat

When the rule chain contains an ai/agent node, it can be executed via the OpenAI-compatible interface, supporting SSE streaming output:

POST /api/v1/rules/{id}/v1/chat/completions
Authorization: Bearer {token}
Content-Type: application/json

{
  "model": "rulego",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true
}

Real-time Debugging

Method	Path	Permission	Description
WS	/api/v1/logs/ws/:chainId/:clientId	Authenticated	WebSocket real-time debugging

WebSocket Connection

ws://{host}:{port}/api/v1/logs/ws/{chainId}/{clientId}?token={jwtToken}

Parameter	Description
chainId	Rule chain ID
clientId	Client unique identifier (custom)
token	JWT token (query parameter)

Server-pushed data includes: node ID, direction (IN/OUT), message data, and metadata.

const ws = new WebSocket(
  'ws://localhost:9090/api/v1/logs/ws/myChain/client001?token=' + token
)
ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log(`[${data.direction}] Node: ${data.nodeId}`, data.msg)
}

The connection supports automatic reconnection (exponential backoff, up to 10 attempts).

Editor Debugging

Visual debugging in RuleGo-Editor: click Run -> configure input -> canvas node colors indicate status (blue = processing, green = success, red = failure) -> bottom console displays IN/OUT data in real time.

Component Management

Method	Path	Permission	Description
GET	/api/v1/components	component:read	Get full component catalog

The response includes endpoints (input endpoints), nodes (processing nodes), tools, and builtins (built-in processors).

Shared Nodes

Method	Path	Permission	Description
GET	/api/v1/shared-nodes	component:read	List shared nodes
POST	/api/v1/shared-nodes/:id/:type	component:write	Create/update shared node
GET	/api/v1/shared-nodes/:id/:type	component:read	Get shared node
DELETE	/api/v1/shared-nodes/:id/:type	component:delete	Delete shared node

Reference in rule chains using the ref:// prefix:

{ "type": "dbClient", "configuration": { "driverName": "ref://mysqlConn" } }

Dynamic Components

Method	Path	Permission	Description
GET	/api/v1/dynamic-components	component:read	List dynamic components
GET	/api/v1/dynamic-components/:id	component:read	Get component DSL
POST	/api/v1/dynamic-components/:id	component:write	Install/upgrade component
DELETE	/api/v1/dynamic-components/:id	component:delete	Uninstall component

Install and uninstall at runtime without restarting the service.

System Configuration

Method	Path	Permission	Description
GET	/api/v1/config/global	config:read	Get global configuration
POST	/api/v1/config/global	config:write	Update global configuration

AI Assistant

Method	Path	Permission	Description
GET	/api/v1/system/agents/:id/prompt	config:read	Get assistant system prompt
POST	/api/v1/system/agents/:id/prompt	config:write	Update assistant system prompt
GET	/api/v1/system/agents/:id/model	config:read	Get assistant model configuration
POST	/api/v1/system/agents/:id/model	config:write	Update assistant model configuration

Skills

Method	Path	Permission	Description
GET	/api/v1/skills	skill:read	List skills
GET	/api/v1/skills/:id	skill:read	Get skill details
POST	/api/v1/skills	skill:write	Create skill
PUT	/api/v1/skills/:id	skill:write	Update skill
DELETE	/api/v1/skills/:id	skill:delete	Delete skill
POST	/api/v1/skills/upload	skill:write	Upload skill (multipart)

Run Logs

Method	Path	Permission	Description
GET	/api/v1/logs/runs	log:read	Query execution history
GET	/api/v1/logs/debug	log:read	Get node debug data
DELETE	/api/v1/logs/runs	log:delete	Delete execution records

Internationalization

Method	Path	Permission	Description
GET	/api/v1/locales	locale:read	List/get language packs
POST	/api/v1/locales	locale:write	Save/update language pack

Component Marketplace

Method	Path	Permission	Description
GET	/api/v1/marketplace/components	marketplace:read	Browse marketplace components
GET	/api/v1/marketplace/chains	marketplace:read	Browse marketplace rule chains

MCP

Method	Path	Authentication	Description
GET/POST/DELETE	/api/v1/mcp/:apiKey	API Key	MCP default endpoint
GET/POST/DELETE	/api/v1/mcp/:apiKey/group/:group	API Key	MCP group endpoint

Static Resources

Method	Path	Description
GET	/	Redirect to /editor/
GET	/editor/*	Editor static files