> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorylake.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Boundary

> 在工作空间内创建一个有名字的记忆范围

```
POST /openapi/memorylake/api/v3/boundaries
```

在某个工作空间内创建一个 Boundary。请求中的每个引用都必须属于该工作空间：项目必须在其中，Actor 和 Agent 必须已绑定到它且未被删除。

<Note>
  **所需权限：** 对该工作空间的 `boundary:create`，以及对请求中引用的每个项目、Actor 和 Agent 的检索权限——参见[权限](/features/memorylake/api-reference/boundaries/overview#权限)
</Note>

### 请求体

<ParamField body="workspace_id" type="string" required>
  Boundary 所属的工作空间。之后不能修改。
</ParamField>

<ParamField body="name" type="string" required>
  显示名称，1 到 255 个字符。
</ParamField>

<ParamField body="custom_id" type="string">
  这个 Boundary 在**您自己系统里的标识符**，最多 255 个字符。在您的租户内必须唯一，设置后不能修改，且不能以 `_sys_` 开头。在[获取 Boundary](/features/memorylake/api-reference/boundaries/get-boundary) 时带上 `by_custom_id=true` 即可用它查找。参见[您自己的标识符](/features/memorylake/api-reference/overview#您自己的标识符)。
</ParamField>

<ParamField body="project_ids" type="string[]">
  范围内的项目。不传或传空数组表示不把范围收窄到特定项目。
</ParamField>

<ParamField body="human_actor_id" type="string">
  范围内的 Actor（即那个人）的 ID。
</ParamField>

<ParamField body="agent_id" type="string">
  其记忆在范围内的 Agent 的 ID。
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://app.memorylake.cn/openapi/memorylake/api/v3/boundaries' \
    -H 'Authorization: Bearer sk_xxxxxx' \
    -H 'Content-Type: application/json' \
    -d '{
      "workspace_id": "ws-8001856949ad4f6a5b6226f415ffa877",
      "name": "Alice Chen - Support Assistant",
      "custom_id": "user-ext-001",
      "project_ids": ["proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"],
      "human_actor_id": "actor-8d093c0578ffeb19f8fa10ea28ee9362",
      "agent_id": "agent-f8bf71ab17ed8eccad8c0e8ae708273f"
    }'
  ```
</RequestExample>

### 响应

<ResponseField name="data" type="object">
  <Expandable title="Boundary">
    <ResponseField name="id" type="string">Boundary ID</ResponseField>
    <ResponseField name="custom_id" type="string">您为 Boundary 设置的自有标识符（如有）</ResponseField>
    <ResponseField name="workspace_id" type="string">Boundary 所属的工作空间</ResponseField>
    <ResponseField name="name" type="string">Boundary 名称</ResponseField>
    <ResponseField name="project_ids" type="string[]">范围内的项目。不把范围收窄到特定项目时不出现。</ResponseField>
    <ResponseField name="human_actor_id" type="string">范围内的 Actor。未设置时不出现。</ResponseField>
    <ResponseField name="agent_id" type="string">其记忆在范围内的 Agent。未设置时不出现。</ResponseField>
  </Expandable>
</ResponseField>

此响应不包含 `created_at` 和 `updated_at`，请通过[获取 Boundary](/features/memorylake/api-reference/boundaries/get-boundary) 读取。

### 错误

| 状态码 | 错误码 | 何时出现 |
| - | - | - |
| `400` | `INVALID_ARGUMENT` | 项目不在该工作空间内，或 Actor / Agent 不存在或未绑定到该工作空间。消息里会指出是哪个字段。 |
| `400` | `ACTOR_INACTIVE` | Actor 或 Agent 已被删除 |
| `403` | `ACCESS_DENIED` | 您没有 `boundary:create`，或对请求中引用的某个对象没有检索权限 |
| `404` | `NOT_FOUND` | 工作空间不存在 |
| `409` | `CUSTOM_ID_CONFLICT` | 您的租户内已有其他 Boundary 使用了这个 `custom_id` |

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "data": {
      "id": "bnd-5e8a2c71d94f4b3a8e6d0c2b7f1a9e34",
      "custom_id": "user-ext-001",
      "workspace_id": "ws-8001856949ad4f6a5b6226f415ffa877",
      "name": "Alice Chen - Support Assistant",
      "project_ids": ["proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"],
      "human_actor_id": "actor-8d093c0578ffeb19f8fa10ea28ee9362",
      "agent_id": "agent-f8bf71ab17ed8eccad8c0e8ae708273f"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.