> ## 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.

# 上传文件

> `save_candidate` 需要的附件（简历 PDF / 截图）不能直接走 JSON 调用，要先用这个 multipart 端点上传，拿到 `file_id` 后作为 `attachment_file_id` 传给 `save_candidate`。

需要 API Key 的 write 权限。



## OpenAPI

````yaml /openapi.json post /files/upload
openapi: 3.1.0
info:
  title: DropCV Skills API
  version: 1.0.0
  description: >-
    DropCV 对外开放的人才库能力接口。所有能力（skill）走统一的调用形态：


    `POST /skills/{skill_key}/invoke`


    用 API Key 鉴权（`Authorization: Bearer drop_cv_...`）。同一套能力也通过 MCP Server 和
    `@dropcv/cli` 命令行暴露。
servers:
  - url: https://api.dropcv.work/api/external/v1
    description: 生产环境
security:
  - ApiKeyAuth: []
paths:
  /files/upload:
    post:
      tags:
        - Files
      summary: 上传文件
      description: >-
        `save_candidate` 需要的附件（简历 PDF / 截图）不能直接走 JSON 调用，要先用这个 multipart 端点上传，拿到
        `file_id` 后作为 `attachment_file_id` 传给 `save_candidate`。


        需要 API Key 的 write 权限。
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - mime_type
              properties:
                file:
                  type: string
                  format: binary
                  description: 文件本体
                mime_type:
                  type: string
                  enum:
                    - application/pdf
                    - image/jpeg
                    - image/png
                  description: 文件 MIME 类型
                original_filename:
                  type: string
                  description: 原始文件名，用于显示（可选）
      responses:
        '200':
          description: 上传成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_id:
                    type: string
                    example: f_01HABCDEFGHIJKLMNOPQRSTUVW
                    description: 文件标识，传给 save_candidate 的 attachment_file_id
                  expires_at:
                    type: string
                    format: date-time
                    description: 未被写 skill 消费时的过期时间（24 小时）
                  size_bytes:
                    type: integer
                    description: 文件大小（字节）
        '403':
          description: API Key 没有 write 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: false
        skill_key:
          type:
            - string
            - 'null'
          example: candidate_search
        invocation_id:
          type: string
          example: inv_01HXXXXXXXXXXXXXXXXXXXXXXX
        error:
          type: object
          properties:
            code:
              type: string
              description: 封闭错误码枚举
              enum:
                - INVALID_API_KEY
                - INSUFFICIENT_PERMISSION
                - SKILL_NOT_FOUND
                - CANDIDATE_NOT_FOUND
                - FILE_NOT_FOUND
                - INVALID_PARAMS
                - BUSINESS_ERROR
                - INTERNAL_ERROR
            message:
              type: string
              description: 人类可读错误说明
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: DropCV API Key。在 设置 → API Keys 生成，格式 drop_cv_<32 位随机字符>。

````