View operator API service configuration¶

Check whether the specified operator version has been released, as well as the name, status, and input definitions required to call the service.

GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workitems/catalog/$NODE_ID/api-service?version=$VERSION

Preparation before calling¶

First View operator list to confirm the operator you want to view and its version. Prepare the personal access token, target workspace ID, operator ID, and version that has access to the target workspace.

Request parameters¶

node_idstringRequired: Operator ID. It can be obtained from the [View operator list](../operator-catalog/list-operators.md) response.
versionstringRequired: Operator version.

Request example

curl "https://api.moi.matrixorigin.cn/v5/workflow/v2/workitems/catalog/$NODE_ID/api-service?version=$VERSION" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Successful response¶

The response returns the service configuration. Only after confirming that the service is enabled can you call service; when calling, the returned service name, version and input definition will be used as is for the request.

The response fields are as follows.

codestring: OK on success.
msgstring: OK on success.
data.service.api_service_idstring: Service ID.
data.service.operator_idinteger: Published custom operator ID.
data.service.node_idstring: Published operator ID.
data.service.versionstring: Published operator version.
data.service.service_namestring: The service name that must be passed in when calling the service.
data.service.statusstring: unpublished means it has not been released yet, ready means it can be called, and disabled means it has been deactivated.
data.service.result_modestring: For operator services, oneshot waits for the execution result and returns it once.
data.service.auth_modestring: The authentication mode of the service.
data.service.methodstring: The HTTP method used to call the service.
data.service.pathstring: Relative path for invocation by workspace and service name; append it to https://api.moi.matrixorigin.cn/v5.
data.service.workflow_idstring: The workflow ID associated with the service; returned if there is a value.
data.service.workflow_def_idstring: The workflow definition ID associated with the service; returned if there is a value.
data.service.workflow_version_idstring: The workflow version ID associated with the service; returned if there is a value.
data.service.input_schemastring: Input data definition. Fill in the payload of the calling request according to its fields and types.
data.service.output_schemastring: Output data definition; returned if there is a value.
data.service.compute_resource_idstring: The computing resource ID used by the service; returned if there is a value.
data.service.timeout_secondsinteger: Timeout for a single call, in seconds; returned if there is a value.
data.service.max_concurrencyinteger: The maximum number of concurrent calls; returned when there is a value.
data.service.rate_limit_per_mininteger: Maximum number of calls per minute; returned if there is a value.
data.service.invokeobject: Information required to call the service; returned if there is a value.
data.service.deploymentobject: Service deployment information; returned if there is a value.

Successful response example

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "service": {
      "api_service_id": "api_2e859efcedc1e0efea48b465b2197784",
      "node_id": "moi:data.sql.process",
      "version": "v1",
      "service_name": "operator-api-37f61ebdaa18aa51",
      "status": "ready",
      "method": "POST",
      "path": "/workspaces/ws-001/dynamic-services/invoke",
      "result_mode": "oneshot",
      "input_schema": "{\"type\":\"object\",\"properties\":{\"sql\":{\"type\":\"string\"}}}"
    }
  }
}

Choose an invocation entry¶

When the service is available, parse data.service.input_schema, prepare payload according to the input definition, and choose an invocation entry:

Entry	URL and request	When to use it
Invoke operator API service	Use the fixed operator-ID URL; provide the service name, operator version, and input in the body.	You have the operator ID and version and want to specify the invocation target explicitly.
Use the configured invocation URL	Append `data.service.path` to `https://api.moi.matrixorigin.cn/v5`; provide the service name and input in the body.	Invoke a published service by workspace and name.

The configured URL and the fixed operator entry are two invocation options. Do not reuse the fixed entry’s request body or response nesting for the configured URL. Invoke operator API service documents the fixed entry’s request and response.

data.service.result_mode is oneshot: the request waits for the execution result and returns it once. Follow the invocation page to check status and errors before accepting the output.

Error response¶

codestring: Error code.
msgstring: Readable error message.
datanull: `null` in an error response.

Error response example

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

Follow-up operations¶

If the service is unpublished, Publish operator API service. If it is disabled, Enable operator API service. When it is available, use Choose an invocation entry to construct the request.

Last updated on Oct 19, 2026