Create custom operator

Create a custom operator that can be used in workflows. Code type operators require source code or source file IDs; built-in binding types use base operators and binding configurations.

HTTP

POST $CLOUDSIGMA_API_BASE/workflow/v2/custom-operators

Before you call this API

Configure the regional API endpoint and authentication, and select the target workspace.

First decide whether to create a code type or a built-in binding type, and prepare the corresponding implementation content.

Request

Input examples

Shell

curl -X POST "$CLOUDSIGMA_API_BASE/workflow/v2/custom-operators" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Text Counter",
    "identifier": "text_counter",
    "node_id": "moi:custom.operator:$WORKSPACE_ID:text_counter",
    "description": "Counts the number of characters in the input text.",
    "language": "python",
    "handler": "main.handle",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "The text to count."
        }
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "description": "Character count."
        }
      }
    },
    "code": "def handle(workspace_id, sdk, input):\n    return {\"count\": len(input[\"text\"])}"
  }'

Show full code

Parameter reference

Request body

Parameter	Type	Required	Description
name	string	Required	Operator name.
identifier	string	Required	Operator ID.
description	string	Required	Operator description.
kind	string		Operator type; when omitted, it is the code type.
language	string		The implementation language of the code type; currently only python is supported.
handler	string		Handler for the code type. Python processing functions use module and function names, such as main.handle; the corresponding function must accept three parameters: workspace_id, sdk and input.
input_schema	object	Required	Input definition. description must be provided for each properties entry.
output_schema	object	Required	Output definition. description must be provided for each properties entry.
version	string		Version for the code type.
isolation_level	string		Isolation configuration for the code type.
code	string		Source code for the code type; provide it instead of source_file_id.
source_file_id	string		Source file ID for the code type; provide it instead of code.
base_node_id	string		Base operator ID required by the built-in binding type.
base_node_version	string		Base operator version required by the built-in binding type.
binding_config	object		Binding configuration required by the built-in binding type.
node_id	string		Custom workflow operator ID. When omitted, the service generates it from the target workspace and identifier.
enabled	boolean		Whether to enable initially.
catalog_id	integer		Associated catalog ID.
database_id	integer		Associated database ID.

Successful response

The response returns the ID and configuration of the newly created operator. Save the operator ID, which will be used for subsequent viewing, updating, trial running, activation, deactivation, and deletion.

The response fields are as follows.

Response example

JSON

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 123,
    "node_id": "moi:custom.operator:workspace:text_counter",
    "name": "Text Counter",
    "identifier": "text_counter",
    "language": 1,
    "kind": 1,
    "input_schema": "{\"type\":\"object\"}",
    "output_schema": "{\"type\":\"object\"}",
    "enabled": true
  }
}

Show full code

Field reference

Field	Type	Description
code	string	OK on success.
msg	string	OK on success.
data.id	integer	Newly created custom operator ID.
data.node_id	string	Operator ID in the workflow.
data.name	string	Operator name.
data.identifier	string	Operator ID.
data.description	string	Operator description; returned if there is a value.
data.language	integer	Implements the numerical encoding of the language. language usage string in request.
data.kind	integer	Numeric encoding of the operator type. kind usage string in request.
data.handler	string	Processing function; returned when there is a value.
data.version	string	Operator version; returned if there is a value.
data.isolation_level	string	Isolation configuration; returned if there is a value.
data.source_file_id	string	Source file ID; returned when created using a source file.
data.input_schema	string	Enter the defined serialization content.
data.output_schema	string	Output the defined serialized content.
data.created_by	string	Creator ID; returned if there is a value.
data.updated_by	string	Last updater ID; returned if there is a value.
data.created_at	integer	Creation timestamp; returned if there is a value.
data.updated_at	integer	Last updated timestamp; returned if there is a value.
data.base_node_id	string	The basic operator associated with the built-in binding type; returned when there is a value.
data.base_node_version	string	The basic operator version associated with the built-in binding type; returned when there is a value.
data.binding_config	string	The serialized content of the binding configuration; returned if there is a value.
data.catalog_id	integer	Associated Catalog ID; returned if there is a value.
data.database_id	integer	The associated database ID; returned if there is a value.
data.enabled	boolean	Whether the operator is enabled.

Error response

Response example

JSON

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

Field reference

Field	Type	Description
code	string	Error code.
msg	string	Readable error message.
data	null	`null` in an error response.

Follow-up operations

Query custom operator details or Trial run custom operator.

Last updated on Sep 15, 2026