# Claim a workspace

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

```text
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

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

```json
{
  "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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

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