Claim a workspace¶

Claim a specified workspace for the current identity and return whether this request performed the claim.

POST https://moi.matrixorigin.cn/newmoi/workspaces/claim

Before you call this API¶

Identify the workspace to claim. Prepare a personal access token and the workspace ID.

The following example uses:

$AI_STUDIO_API_KEY: Your personal access token, passed in the X-API-Key header.
$WORKSPACE_ID: The workspace ID to claim, passed in the request body’s workspace_id field.

The calling identity is the claim target. You cannot specify another user in the request.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/claim" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'$WORKSPACE_ID'"
  }'

Request body¶

Parameter	Type	Required	Description
`workspace_id`	string	Yes	ID of the workspace to claim.

Successful response¶

On success, the API returns 200. Use the claim result fields to determine whether the workspace was claimed by this request.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace_id": "ws_01",
    "claimed": true,
    "already_claimed": false
  }
}

Response fields:

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.workspace_id`	string	ID of the claimed workspace.
`data.claimed`	boolean	Whether this request completed a claim.
`data.already_claimed`	boolean	Whether the workspace was already claimed by the current identity before the request.

Error response¶

{
  "code": "ErrWorkspaceNotFound",
  "msg": "Workspace not found",
  "data": null
}

Common HTTP errors¶

HTTP status	Error code	Common cause	Recommended action
`400`	`ErrParamInvalid`	`workspace_id` is missing or empty.	Provide a valid workspace ID and retry.
`401`	`Unauthorized`	Credentials are missing or invalid.	Check the personal access token.
`403`	`ErrUserNotSynced` or `ErrNotOrgAdmin`	The current identity has not been synchronized or cannot claim workspaces.	Complete account synchronization, or ask an administrator for access before retrying.
`404`	`ErrAccountNotFound` or `ErrWorkspaceNotFound`	The current account or target workspace does not exist.	Check the workspace ID and confirm the current account is available.
`409`	`ErrWorkspaceClaiming` or `ErrWorkspaceMembershipRequired`	The workspace is being claimed, or the current identity must first be a member.	Wait for the current operation to finish, or resolve the membership requirement first.
`410`	`ErrWorkspaceRolledBack`	The workspace was rolled back.	Confirm the workspace again, then make a new claim request.
`503`	`UNAVAILABLE`	A dependent service is temporarily unavailable.	Retry later.
`500`	`ErrServer`	The service could not complete the claim.	Record the request time and error message, then retry.

Last updated on Sep 3, 2026