Invoke a dynamic API service¶
Invoke a published and ready operator API service or dynamic-service workflow by service name and wait for the execution result. HTTP 200 indicates only that the HTTP request returned; inspect data.status and data.error before consuming the business output.
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/dynamic-services/invoke
Before you begin¶
Prepare a personal access token with run permission on the target service and the target workspace ID.
For an operator API service, call View operator API service configuration first to verify that
data.service.statusisreadyand recordservice_nameandinput_schema; for a dynamic-service workflow, call List workflows (withinclude_dynamic_service=true) to verify that the workflow status isreadyand the service name is unique in the workspace.
Request parameters¶
Replace $AI_STUDIO_API_KEY, $WORKSPACE_ID, $SERVICE_NAME, and the example input fields with actual values. You can also call the equivalent header-scoped endpoint POST https://api.moi.matrixorigin.cn/v5/workflow/v2/dynamic-services/invoke, which omits the workspace_id path parameter and resolves the target workspace directly from X-Workspace-ID.
JSON request
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/dynamic-services/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"'",
"payload": {
"sql": "SELECT now()"
}
}'
Multipart file request
When uploading files with -F, let cURL generate the Content-Type header and boundary automatically instead of overriding it manually.
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/dynamic-services/invoke" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-F "service_name=$SERVICE_NAME" \
-F 'payload={"language":"zh"}' \
-F "file=@sample.pdf;type=application/pdf"
Path parameters
Parameter |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Target workspace ID. Must match |
Body parameters
Parameter |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Name of the target dynamic service or operator API service. Leading and trailing whitespace is trimmed, and the name must be unique among dynamic services in the workspace. |
|
object |
Yes |
Business input object passed to the service. Must not be empty or |
|
string |
No |
Optional version label string. The executed workflow version is resolved from |
|
integer |
No |
Positive integer workflow version number to invoke. When omitted or less than or equal to |
|
object |
No |
Per-invocation execution tracing options. In |
|
boolean |
No |
Whether tracing is enabled for this invocation. |
|
integer |
No |
Tracing granularity code: |
|
boolean |
No |
Whether input and output payloads are included in trace attributes. |
|
integer |
No |
Maximum byte size for trace attribute JSON; |
|
binary |
No |
Used only in |
multipart/form-data file materialization rules:
service_name,payload,version,version_number, andtraceare reserved form fields and cannot be uploaded as file parts.Each uploaded file is stored in the workspace file catalog and converted into a
{"file_id": "...", "original_name": "..."}reference object.When the file field is named
sources, or namedfilewithout an explicitfilekey inpayload, the file references are written or appended topayload.sources; for any other field name, a single uploaded file setspayload.<file_field>to the reference object and multiple files under the same field name setpayload.<file_field>to an array of reference objects.
Successful response¶
{
"code": "OK",
"msg": "OK",
"data": {
"case_id": "case-001",
"status": "COMPLETED",
"result": {
"rows": [
{
"now": "2026-08-28 10:00:00"
}
]
}
}
}
Field |
Type |
Description |
|---|---|---|
|
string |
|
|
string |
Response status message. |
|
object |
Returned invocation result for the dynamic service. |
|
string |
Execution case ID for this call; omitted when empty. |
|
string |
Terminal execution status. Non-streaming ( |
|
any |
Service output JSON value (in streaming mode, the last non-empty event payload); omitted when there is no output. |
|
string |
Execution error message; omitted when empty. An execution failure can still return HTTP |
|
array of object |
Ordered stream event frames collected in streaming ( |
|
string |
Execution case ID that emitted the event; omitted when empty. |
|
any |
JSON payload carried by the stream event; omitted when empty. |
|
boolean |
Whether this frame marks the end of the stream. |
|
string |
Error message carried by the stream event; omitted when empty. |
Treat data.result as valid output only when data.status indicates completion (COMPLETED or completed) and data.error is empty. If service_name matches an agent automation API-triggered task in the workspace, the endpoint returns HTTP 202 with an asynchronous run receipt (data.run_id, data.status, data.result_url).
Error response¶
Missing parameters, disabled services, concurrency or rate limit violations, or missing service names return a non-200 HTTP error. Internal execution failures after submission can still return HTTP 200; always inspect data.status and data.error.
{
"code": "api_service_disabled",
"msg": "Conflict"
}
Field |
Type |
Description |
|---|---|---|
|
string |
Error code. |
|
string |
Readable error message. |
Common HTTP errors¶
HTTP status |
Error code |
Common cause |
Suggested action |
|---|---|---|---|
400 |
|
|
Check the request body, multipart limits, workspace ID, and service input definition. |
401 |
|
Authentication credentials are missing or invalid. |
Check the credential in the |
403 |
|
The current identity lacks run permission on the target operator API service or dynamic-service workflow. |
Use an authorized identity, or request access from an administrator. |
404 |
|
No dynamic service matches |
Verify service name uniqueness, target workspace, and version number. |
409 |
|
The target operator API service or dynamic-service workflow is not in |
Enable operator API service or resume the dynamic-service workflow before calling. |
429 |
|
Exceeded the configured maximum concurrency or per-minute rate limit of the service. |
Reduce request concurrency or rate and retry later. |
500 |
|
Internal server failure or wait timeout. A wait timeout does not guarantee that the underlying run was not started. |
Inspect target state and run records before resubmitting non-idempotent requests. |
503 |
|
Runtime, authorization, or storage dependencies are temporarily unavailable. |
Recheck run status and retry after dependencies recover. |