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

  1. Prepare a personal access token with run permission on the target service and the target workspace ID.

  2. For an operator API service, call View operator API service configuration first to verify that data.service.status is ready and record service_name and input_schema; for a dynamic-service workflow, call List workflows (with include_dynamic_service=true) to verify that the workflow status is ready and 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

workspace_id

string

Yes

Target workspace ID. Must match X-Workspace-ID when that header is also sent; omitted when calling /v5/workflow/v2/dynamic-services/invoke.

Body parameters

Parameter

Type

Required

Description

service_name

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.

payload

object

Yes

Business input object passed to the service. Must not be empty or null, and its fields must conform to the target version’s input_schema. In multipart/form-data requests, pass a JSON object string (defaults to {} when omitted).

version

string

No

Optional version label string. The executed workflow version is resolved from version_number or the service’s latest published version.

version_number

integer

No

Positive integer workflow version number to invoke. When omitted or less than or equal to 0, invokes the latest published version; returns 404 if the specified version does not exist. In multipart/form-data requests, pass a base-10 integer string.

trace

object

No

Per-invocation execution tracing options. In multipart/form-data requests, pass a JSON object string.

trace.enabled

boolean

No

Whether tracing is enabled for this invocation.

trace.level

integer

No

Tracing granularity code: 0 unspecified, 1 workflow level, 2 node level, 3 worker level, 4 stream level.

trace.include_payloads

boolean

No

Whether input and output payloads are included in trace attributes.

trace.max_attr_bytes

integer

No

Maximum byte size for trace attribute JSON; 0 uses the server default.

<file_field>

binary

No

Used only in multipart/form-data requests. File upload part under any non-reserved field name; up to 16 files per request and up to 64 MiB per file.

multipart/form-data file materialization rules:

  • service_name, payload, version, version_number, and trace are 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 named file without an explicit file key in payload, the file references are written or appended to payload.sources; for any other field name, a single uploaded file sets payload.<file_field> to the reference object and multiple files under the same field name set payload.<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

code

string

OK when the HTTP request is processed; does not by itself indicate that service execution succeeded.

msg

string

Response status message.

data

object

Returned invocation result for the dynamic service.

data.case_id

string

Execution case ID for this call; omitted when empty.

data.status

string

Terminal execution status. Non-streaming (oneshot) services return uppercase status words (such as COMPLETED, FAILED, CANCELLED), while streaming (stream) services return lowercase status words (completed, failed).

data.result

any

Service output JSON value (in streaming mode, the last non-empty event payload); omitted when there is no output.

data.error

string

Execution error message; omitted when empty. An execution failure can still return HTTP 200.

data.events

array of object

Ordered stream event frames collected in streaming (stream) result mode; omitted in non-streaming mode.

data.events[].case_id

string

Execution case ID that emitted the event; omitted when empty.

data.events[].data

any

JSON payload carried by the stream event; omitted when empty.

data.events[].done

boolean

Whether this frame marks the end of the stream.

data.events[].error

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

code

string

Error code.

msg

string

Readable error message.

Common HTTP errors

HTTP status

Error code

Common cause

Suggested action

400

ErrParamInvalid, ErrWorkspaceRequired, ErrWorkflowComputeResourceNotFound

service_name or payload is missing, path workspace_id differs from X-Workspace-ID, uploaded files exceed 16 files or 64 MiB per file, or the compute resource is unavailable.

Check the request body, multipart limits, workspace ID, and service input definition.

401

Unauthorized, ErrUnauthorized

Authentication credentials are missing or invalid.

Check the credential in the X-API-Key header.

403

ErrForbidden

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

ErrNotFound

No dynamic service matches service_name in the workspace, duplicate dynamic services share the same name, or version_number does not exist.

Verify service name uniqueness, target workspace, and version number.

409

api_service_disabled

The target operator API service or dynamic-service workflow is not in ready status (for example, disabled or paused).

Enable operator API service or resume the dynamic-service workflow before calling.

429

ErrDynamicServiceConcurrencyLimit, ErrDynamicServiceRateLimit

Exceeded the configured maximum concurrency or per-minute rate limit of the service.

Reduce request concurrency or rate and retry later.

500

ErrServer

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

ErrServiceUnavailable

Runtime, authorization, or storage dependencies are temporarily unavailable.

Recheck run status and retry after dependencies recover.

Last updated on