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

# API 协议

> 请求/响应 envelope，封闭错误码枚举。

## URL

所有 skill 调用走同一形态：

```
POST /api/external/v1/skills/{skill_key}/invoke
```

辅助端点：

```
GET  /api/external/v1/skills              # 列出可用 skill
GET  /api/external/v1/skills/{skill_key}  # 单 skill 元数据 + Pydantic schema
POST /api/external/v1/files/upload        # 文件上传，详见文件上传页
```

## 请求 envelope

```http theme={null}
POST /api/external/v1/skills/candidate_search/invoke
Authorization: Bearer drop_cv_xxxxx...
Content-Type: application/json

{
  "params": { "query": "Python 后端 5 年", "top_k": 10 }
}
```

`params` 字典就是该 skill 的 schema 定义。每个 skill 的 params 详见对应文档。

## 响应 envelope（成功）

```json theme={null}
{
  "success": true,
  "skill_key": "candidate_search",
  "invocation_id": "inv_01HXXXXXXX...",
  "result": { /* skill 自己的输出，参考对应 skill 文档 */ },
  "metadata": { "latency_ms": 234 }
}
```

## 响应 envelope（失败）

```json theme={null}
{
  "success": false,
  "skill_key": "candidate_search",
  "invocation_id": "inv_01HXXXXXXX...",
  "error": { "code": "INVALID_PARAMS", "message": "query is empty" }
}
```

## 错误码

| code                      | HTTP | 含义                                         | 怎么修                     |
| ------------------------- | ---- | ------------------------------------------ | ----------------------- |
| `INVALID_API_KEY`         | 401  | Key 无效 / 撤销 / 不存在                          | 检查 Authorization 头，重新生成 |
| `INSUFFICIENT_PERMISSION` | 403  | 写 skill 但 key 没开 write 权限                  | 在 API Keys 页面勾"允许写入"    |
| `SKILL_NOT_FOUND`         | 404  | skill\_key 拼错                              | 看 `GET /skills` 列表      |
| `CANDIDATE_NOT_FOUND`     | 404  | candidate\_id 不存在或不属于本账号                   | 核对 candidate\_id        |
| `FILE_NOT_FOUND`          | 404  | attachment\_file\_id 不存在 / 已过期 / 不属于本 user | 重新上传文件                  |
| `BUSINESS_ERROR`          | 400  | 入参语义不合法（依赖资源状态不对等）                         | 看 message 说明            |
| `INVALID_PARAMS`          | 422  | params 不符合 schema                          | 看 message 里的字段错误说明      |
| `INTERNAL_ERROR`          | 500  | 服务端业务异常                                    | 凭 invocation\_id 联系支持   |

## invocation\_id

每次调用都会生成 `inv_<ULID>` 格式的 id。**记录它**——如果调用结果有问题：

* 在 [DropCV 设置 → 用量](https://app.dropcv.work/dashboard/settings/usage) 里按 invocation\_id 搜索能看到完整调用详情（参数、状态、延迟、错误信息）
* 联系支持时附上这个 id 便于快速定位

CLI 出错时会自动在 stderr 打印 `invocation_id`；MCP 客户端通常不显示但也会写入审计。