Create tool

Creates a platform tool in the current workspace. After successful creation, the tool definition and its current bindable status are returned.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools

Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: The workspace ID of the tool to be created, passed through the X-Workspace-ID Header.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "查询工具",
    "kind": "http_api",
    "side_effect_class": "read"
  }'

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	The current workspace ID.

Request body

Field	Type	Is it required	Description
name	string	Yes	Tool name.
description	string	No	Tool description and display classification.
status	string	No	Tool description and display classification.
kind	string	No	Tool description and display classification.
category	string	No	Tool description and display classification.
icon_ref	string	No	Tool description and display classification.
tags	string[]	No	Tool description and display classification.
phase	string	No	Tool description and display classification.
market_metadata	object	No	Tool market presentation and distribution metadata.
source_ref	object	No	Tool source; can include type, id, uri, version, and config.
input_schema	object	No	Input and output JSON Schema.
output_schema	object	No	Input and output JSON Schema.
side_effect_class	string	No	Side effect classification: read, write, or external_effect.
credential_ref	string	No	Credentials, approvals, and masking policy references.
approval_policy_ref	string	No	Credentials, approvals, and masking policy references.
redaction_policy_ref	string	No	Credentials, approvals, and masking policy references.
sync	object	No	Synchronization status, can include status, last_sync_at, and last_sync_error.
labels	object	No	Extended tags, comments, and metadata.
annotations	object	No	Extended tags, comments, and metadata.
metadata	object	No	Extended tags, comments, and metadata.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Successful response

Returns 201 on success.

{
  "code": 0,
  "data": {
    "id": "tool_01",
    "workspace_id": "ws_01",
    "name": "查询工具",
    "status": "draft",
    "kind": "http_api",
    "side_effect_class": "read",
    "version": 1,
    "bindable": true,
    "supported_runtimes": [],
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.id	string	Tool ID, workspace and name.
data.workspace_id	string	Tool ID, workspace and name.
data.name	string	Tool ID, workspace and name.
data.status	string	Tool status, category and side effect classification.
data.kind	string	Tool status, category and side effect classification.
data.side_effect_class	string	Tool status, category and side effect classification.
data.source_ref	object	Source, input schema, and output schema; not returned if not set.
data.input_schema	object	Source, input schema, and output schema; not returned if not set.
data.output_schema	object	Source, input schema, and output schema; not returned if not set.
data.version	integer	Tool resource version.
data.bindable	boolean	Current binding capabilities, reasons for unbinding, and supported operating environments.
data.bindability_reason	string	Current binding capabilities, reasons for unbinding, and supported operating environments.
data.supported_runtimes	string[]	Current binding capabilities, reasons for unbinding, and supported operating environments.
data.created_at	string	Creation and last update times, using RFC 3339 format.
data.updated_at	string	Creation and last update times, using RFC 3339 format.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response

{
  "code": 2,
  "message": "<错误信息>"
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	The request body, tool definition, or credential reference is invalid.	Check field values ​​and associated resources.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to create tools in the workspace.	Check workspace authorization.
409	4（ALREADY_EXISTS）	The tool ID or tool definition already exists.	Change tool ID or check existing tool.
503	15（UNAVAILABLE）	Tool resource services or authorization dependencies are temporarily unavailable.	Try again later.

Follow-up operations

After the creation is completed, Query tool details confirms the result.

Last updated on Sep 3, 2026