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

# 注册 Resource

> 将已有资源注册为 Forward Resource。

`POST /api/v1/forward/resources/registry`

按资源 ID 注册已有资源。接口为 upsert 语义：首次注册返回 `201 Created`，后续注册更新返回 `200 OK`。

## 请求头

| Header          | 是否必填 | 说明                 |
| --------------- | ---- | ------------------ |
| Authorization   | 是    | `Bearer <PAT>`     |
| Content-Type    | 是    | `application/json` |
| Idempotency-Key | 否    | 有副作用请求可选的幂等键。      |

## 请求体参数

| 参数          | 类型     | 是否必填 | 说明                                            |
| ----------- | ------ | ---- | --------------------------------------------- |
| type        | string | 是    | 资源类型，支持 `skill`、`file`、`vault`、`environment`。 |
| resource    | object | 是    | 资源对象，仅使用 `resource.id`。                       |
| resource.id | string | 是    | 资源 ID，例如 `skill_...` 或 `file_...`。            |

## 示例请求

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/resources/registry' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "skill",
  "resource": {
    "id": "skill_xxx"
  }
}'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "id": "skill_xxx",
  "type": "skill"
}
```

## 响应字段

| 字段   | 类型     | 说明                             |
| ---- | ------ | ------------------------------ |
| id   | string | Forward Resource ID，直接等于资源 ID。 |
| type | string | 资源类型。                          |

## 错误

| HTTP | Type                    | Code                      | 触发条件                                     |
| ---- | ----------------------- | ------------------------- | ---------------------------------------- |
| 400  | `invalid_request_error` | -                         | 缺少或不支持 `type`、缺少 `resource.id`，或请求体格式非法。 |
| 403  | `permission_error`      | -                         | 当前调用方无权访问该资源。                            |
| 404  | `not_found_error`       | -                         | 资源不存在，或声明的 `type` 与实际类型不匹配。              |
| 401  | `authentication_error`  | `authentication_required` | PAT 无效或已过期。                              |

## 注意事项

* 请先通过资源 API 创建或更新资源，再注册到 Forward。

## 相关

<CardGroup cols={2}>
  <Card title="列出 Resources" icon="list" href="/cloud-agents/api/forward/resources/list" />

  <Card title="创建 Template" icon="plus" href="/cloud-agents/api/forward/templates/create" />
</CardGroup>