# Invoke a dynamic API service

<span id="调用动态-api-服务"></span>

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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.

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/dynamic-services/invoke
```

<span id="调用前准备"></span>

## Before you begin

1. Prepare a [personal access token](../../../../../guides/genesis/api-keys.md#creating-and-managing-personal-access-tokens) with run permission on the target service and the [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-the-workspace-id).
2. For an operator API service, call [View operator API service configuration](get-operator-api-service.md#successful-response) first to verify that `data.service.status` is `ready` and record `service_name` and `input_schema`; for a dynamic-service workflow, call [List workflows](../workflows/list-workflows.md) (with `include_dynamic_service=true`) to verify that the workflow status is `ready` and the service name is unique in the workspace.

<span id="请求参数"></span>

## 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`.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

### JSON request

```bash
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.

```bash
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"
```

:::::
:::::{tab-item} Parameters

### 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.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "case_id": "case-001",
    "status": "COMPLETED",
    "result": {
      "rows": [
        {
          "now": "2026-08-28 10:00:00"
        }
      ]
    }
  }
}
```

:::::
:::::{tab-item} Fields

| 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`).

:::::
::::::
:::::::

<span id="错误响应"></span>

## 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`.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "api_service_disabled",
  "msg": "Conflict"
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Readable error message. |

:::::
::::::
:::::::

### Common HTTP errors

```{list-table}
:header-rows: 1

* - 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](enable-operator-api-service.md) 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.
```
