# 库 (/docs/api/native/vault/vaults)



创建和管理库，检查可用状态，并查询不含 Secret 值的审计事件。

[指南 →](/docs/cloud/services/vault/quickstart)

[基础地址与鉴权](/docs/api/native/vault)

审计事件按时间倒序列出，可用 secret 按名称或 ID 过滤；未知 Secret 返回空列表。limit 默认 50、最大 200；超限或无效 cursor 返回 400 INVALID\_PARAMS。事件没有按天自动过期的保留期；归档保留事件，删除库或 Secret 会清除其历史事件，仅保留删除记录。

## 列出库 [#列出库]

`GET /vault/v1/vaults`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| cursor | query | 上一页返回的 next_cursor。 |
| limit | query | 每页条数。 (默认: 50) (1–200) |
| include_archived | query | 是否包含已归档的条目。 (默认: false) |

### 响应 [#响应]

#### HTTP 200 [#http-200]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| data | Vault[] | 是 | 条目数组 |
| data[].id | string | 是 | 对象标识符 |
| data[].type | "vault" | 是 | 对象类型 |
| data[].display_name | string | 是 | 显示名称，1–255 个字符 |
| data[].metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| data[].status | "active" / "archived" | 是 | 状态 |
| data[].secret_count | integer | 是 | 有效 Secret 数 |
| data[].needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| data[].created_at | date-time | 是 | 创建时间 |
| data[].updated_at | date-time | 是 | 更新时间 |
| data[].archived_at | date-time / null | 是 | 归档时间；未归档时为 null |
| next_cursor | string / null | 是 | 下一页游标；没有后续时为 null |

### 错误响应 [#错误响应]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |

```bash
curl "https://api.deepraxis.ai/vault/v1/vaults" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## 创建库 [#创建库]

`POST /vault/v1/vaults`

### 请求体 [#请求体]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| display_name | string | 是 | 显示名称，1–255 个字符 |
| metadata | object | 否 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |

### 响应 [#响应-1]

#### HTTP 200 [#http-200-1]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 对象标识符 |
| type | "vault" | 是 | 对象类型 |
| display_name | string | 是 | 显示名称，1–255 个字符 |
| metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| status | "active" / "archived" | 是 | 状态 |
| secret_count | integer | 是 | 有效 Secret 数 |
| needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| archived_at | date-time / null | 是 | 归档时间；未归档时为 null |

### 错误响应 [#错误响应-1]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |

```bash
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Agent credentials"}'
```

## 检查库 [#检查库]

`POST /vault/v1/vaults:check`

### 请求体 [#请求体-1]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| vault_ids | string[] | 是 | 要检查的库 ID |

### 响应 [#响应-2]

#### HTTP 200 [#http-200-2]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| data | object[] | 是 | 条目数组 |
| data[].vault_id | string | 是 | 库 ID |
| data[].status | "ok" / "not_found" / "archived" | 是 | 状态 |

### 错误响应 [#错误响应-2]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |

```bash
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults:check" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"vault_ids\":[\"${VAULT_ID}\"]}"
```

## 读取库 [#读取库]

`GET /vault/v1/vaults/{vault_id}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| vault_id | path | 库 ID。 |

### 响应 [#响应-3]

#### HTTP 200 [#http-200-3]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 对象标识符 |
| type | "vault" | 是 | 对象类型 |
| display_name | string | 是 | 显示名称，1–255 个字符 |
| metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| status | "active" / "archived" | 是 | 状态 |
| secret_count | integer | 是 | 有效 Secret 数 |
| needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| archived_at | date-time / null | 是 | 归档时间；未归档时为 null |

### 错误响应 [#错误响应-3]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| VAULT_NOT_FOUND | 404 | 库不存在或不属于当前账户；检查库 ID | validation_failure | none | 否 |

```bash
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## 更新库 [#更新库]

`POST /vault/v1/vaults/{vault_id}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| vault_id | path | 库 ID。 |

### 请求体 [#请求体-2]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| display_name | string | 否 | 显示名称，1–255 个字符 |
| metadata | object | 否 | 按键合并：字符串写入，null 删除，省略的键保留；自定义标签最多 16 对 |

### 响应 [#响应-4]

#### HTTP 200 [#http-200-4]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 对象标识符 |
| type | "vault" | 是 | 对象类型 |
| display_name | string | 是 | 显示名称，1–255 个字符 |
| metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| status | "active" / "archived" | 是 | 状态 |
| secret_count | integer | 是 | 有效 Secret 数 |
| needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| archived_at | date-time / null | 是 | 归档时间；未归档时为 null |

### 错误响应 [#错误响应-4]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| VAULT_NOT_FOUND | 404 | 库不存在或不属于当前账户；检查库 ID | validation_failure | none | 否 |
| VAULT_INVALID_STATE | 409 | 向已归档的库或 Secret 写入；改用有效资源 | validation_failure | none | 否 |
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |

```bash
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"team":"growth"}}'
```

## 删除库 [#删除库]

`DELETE /vault/v1/vaults/{vault_id}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| vault_id | path | 库 ID。 |

### 响应 [#响应-5]

#### HTTP 200 [#http-200-5]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 对象标识符 |
| type | "vault_deleted" | 是 | 对象类型 |

### 错误响应 [#错误响应-5]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| VAULT_NOT_FOUND | 404 | 库不存在或不属于当前账户；检查库 ID | validation_failure | none | 否 |

```bash
curl -X DELETE "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## 归档库 [#归档库]

`POST /vault/v1/vaults/{vault_id}/archive`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| vault_id | path | 库 ID。 |

### 响应 [#响应-6]

#### HTTP 200 [#http-200-6]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 对象标识符 |
| type | "vault" | 是 | 对象类型 |
| display_name | string | 是 | 显示名称，1–255 个字符 |
| metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| status | "active" / "archived" | 是 | 状态 |
| secret_count | integer | 是 | 有效 Secret 数 |
| needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| archived_at | date-time / null | 是 | 归档时间；未归档时为 null |

### 错误响应 [#错误响应-6]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| VAULT_NOT_FOUND | 404 | 库不存在或不属于当前账户；检查库 ID | validation_failure | none | 否 |

```bash
curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## 查看事件 [#查看事件]

`GET /vault/v1/vaults/{vault_id}/events`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| vault_id | path | 库 ID。 |
| secret | query | Secret 名称或 vsec_ 开头的 ID。 |
| cursor | query | 上一页返回的 next_cursor。 |
| limit | query | 每页条数。 (默认: 50) (1–200) |

### 响应 [#响应-7]

#### HTTP 200 [#http-200-7]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| data | VaultEvent[] | 是 | 条目数组 |
| data[].id | uuid | 是 | 对象标识符 |
| data[].type | "vault.created" / "vault.updated" / "vault.archived" / "vault.deleted" / "vault_secret.created" / "vault_secret.updated" / "vault_secret.archived" / "vault_secret.deleted" / "vault_secret.used" / "vault_secret.refreshed" / "vault_secret.refresh_failed" / "vault_authorization.completed" / "vault_authorization.failed" / "vault_authorization.expired" | 是 | 对象类型 |
| data[].secret_id | string / null | 是 | 关联的 Secret ID；未关联时为 null |
| data[].secret_name | string / null | 是 | 关联的 Secret 名称 |
| data[].at | date-time | 是 | 事件或错误发生时间 |
| data[].detail | object / null | 是 | 事件详情，不含 Secret 值；更新事件的 changed 列出变更字段 |
| data[].detail.changed | string[] | 否 | 本次更新的字段名，例如 value、allowed_hosts |
| next_cursor | string / null | 是 | 下一页游标；没有后续时为 null |

### 错误响应 [#错误响应-7]

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| VAULT_NOT_FOUND | 404 | 库不存在或不属于当前账户；检查库 ID | validation_failure | none | 否 |
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |

```bash
curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/events" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

## Vault [#vault]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 对象标识符 |
| type | "vault" | 是 | 对象类型 |
| display_name | string | 是 | 显示名称，1–255 个字符 |
| metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| status | "active" / "archived" | 是 | 状态 |
| secret_count | integer | 是 | 有效 Secret 数 |
| needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| archived_at | date-time / null | 是 | 归档时间；未归档时为 null |

## VaultPage [#vaultpage]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| data | Vault[] | 是 | 条目数组 |
| data[].id | string | 是 | 对象标识符 |
| data[].type | "vault" | 是 | 对象类型 |
| data[].display_name | string | 是 | 显示名称，1–255 个字符 |
| data[].metadata | object | 是 | 自定义标签最多 16 对，键最长 64 字符，值最长 512 字符 |
| data[].status | "active" / "archived" | 是 | 状态 |
| data[].secret_count | integer | 是 | 有效 Secret 数 |
| data[].needs_reauthorization_count | integer | 是 | 续期失败、需要重新授权的 OAuth Secret 数 |
| data[].created_at | date-time | 是 | 创建时间 |
| data[].updated_at | date-time | 是 | 更新时间 |
| data[].archived_at | date-time / null | 是 | 归档时间；未归档时为 null |
| next_cursor | string / null | 是 | 下一页游标；没有后续时为 null |

## VaultEvent [#vaultevent]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | uuid | 是 | 对象标识符 |
| type | "vault.created" / "vault.updated" / "vault.archived" / "vault.deleted" / "vault_secret.created" / "vault_secret.updated" / "vault_secret.archived" / "vault_secret.deleted" / "vault_secret.used" / "vault_secret.refreshed" / "vault_secret.refresh_failed" / "vault_authorization.completed" / "vault_authorization.failed" / "vault_authorization.expired" | 是 | 对象类型 |
| secret_id | string / null | 是 | 关联的 Secret ID；未关联时为 null |
| secret_name | string / null | 是 | 关联的 Secret 名称 |
| at | date-time | 是 | 事件或错误发生时间 |
| detail | object / null | 是 | 事件详情，不含 Secret 值；更新事件的 changed 列出变更字段 |
| detail.changed | string[] | 否 | 本次更新的字段名，例如 value、allowed_hosts |