Invoke operator API service¶

Execute a published and enabled operator service and wait for its result. Check the execution status and errors before reading the output.

POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workitems/catalog/{node_id}/api-service/invoke

Preparation before calling¶

First View operator API service configuration to select an available service and confirm its operator version, name, and input definition. Prepare a personal access token with access to the target workspace and the target workspace ID.

Request example¶

This example uses a text-counting operator. $AI_STUDIO_API_KEY is the personal access token and $WORKSPACE_ID is the target workspace ID; the remaining variables are described below. Replace payload according to the selected service input definition.

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workitems/catalog/$NODE_ID/api-service/invoke" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "service_name": "'"$SERVICE_NAME"'",
  "version": "'"$VERSION"'",
  "payload": {
    "text": "hello, MOI!"
  }
}'

Path parameters¶

Parameter	Type	Required	Description
`node_id`	string	Yes	Operator ID; set `$NODE_ID` to `data.service.node_id` from the service configuration.

Request body¶

Field	Type	Required	Description
`service_name`	string	Yes	Service name; set `$SERVICE_NAME` to `data.service.service_name` from the service configuration.
`version`	string	Yes	Published operator version; set `$VERSION` to `data.service.version`, matching the operator in the path.
`payload`	object	Yes	Operator input; fields and types must conform to `data.service.input_schema`.

The input definition in the configuration is a JSON string. Parse it and construct the input using its required fields and types.

Successful response¶

Operator API services use oneshot mode: the request waits for the execution result, so polling this invocation endpoint is unnecessary. A successful HTTP response can still contain an execution failure.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "result": {
      "case_id": "case-example",
      "status": "COMPLETED",
      "result": "{\"count\":11}"
    }
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` when the API request succeeds; it does not establish execution success.
`msg`	string	Readable API request message.
`data`	object	Response data.
`data.result`	object	Execution result for this call.
`data.result.case_id`	string	Execution ID for this call.
`data.result.status`	string	Execution status; see the completion and failure handling below.
`data.result.result`	string	Operator output as a JSON string; returned when the execution succeeds with output.
`data.result.error`	string	Execution error; returned when an error occurs.

Check the execution result¶

Treat the execution as successful only when data.result.status is COMPLETED and data.result.error is absent or empty. Parse data.result.result as a JSON string; this example produces {"count":11}. The actual output follows the operator output definition.

When data.result.status is FAILED, inspect data.result.error and stop processing the output. Do not treat missing statuses, other statuses, or responses containing errors as successful.

Execution failure response shape:

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "result": {
      "case_id": "case-example",
      "status": "FAILED",
      "error": "Operator execution failed"
    }
  }
}

Error response¶

Invalid input or a disabled service can produce a non-success HTTP status. Execution failures can still return HTTP 200; handle them using the execution result rules above.

{
  "code": "ErrParamInvalid",
  "msg": "Invalid request parameters",
  "data": null
}

Common HTTP errors¶

HTTP status	Error code	Common cause	Suggested action
400	`ErrParamInvalid`	Input is missing required fields or does not satisfy the input definition.	Correct the request using the service input definition.
409	`api_service_disabled`	The operator API service is disabled.	Enable operator API service before invoking it.

Follow-up operations¶

To check service availability or its input definition, use the same operator ID and version to View operator API service configuration.

Last updated on Oct 19, 2026