post:
  summary: Upload release
  x-auth-scopes: [upload_release]
  parameters:
    - name: project_id
      in: path
      required: true
      schema:
        type: string
  requestBody:
    required: true
    content:
      multipart/form-data:
        schema:
          type: object
          required:
            - version
            - sha256
            - artifact
          properties:
            version:
              type: string
              pattern: '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'
              example: 1.2.3
            sha256:
              type: string
              example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
            sig_url:
              type: string
              format: uri
              description: Optional reference to a detached signature
            signature:
              type: string
              format: binary
              description: Detached signature file (optional alternative to sig_url)
            key_id:
              type: string
              description: Public key identifier for signature verification
            artifact:
              type: string
              format: binary
  responses:
    '201':
      description: Created
      content:
        application/json:
          schema:
            $ref: '../schemas/upload-response.yaml'
          examples:
            created:
              value:
                version: 1.2.3
                manifest_url: https://update.wlkns.org/v1/projects/demo/manifest
                active: true
    '400':
      description: Bad Request
      x-error-codes: [invalid_payload]
      content:
        application/json:
          schema:
            $ref: '../schemas/error.yaml'
          examples:
            invalid_payload:
              value:
                code: invalid_payload
                message: Missing required fields
    '401':
      description: Unauthorized
      x-error-codes: [unauthorized]
      content:
        application/json:
          schema:
            $ref: '../schemas/error.yaml'
          examples:
            unauthorized:
              value:
                code: unauthorized
                message: Missing or invalid token
    '409':
      description: Conflict
      x-error-codes: [version_exists]
      content:
        application/json:
          schema:
            $ref: '../schemas/error.yaml'
          examples:
            version_exists:
              value:
                code: version_exists
                message: Version already exists
    '413':
      description: Payload Too Large
      x-error-codes: [payload_too_large]
      content:
        application/json:
          schema:
            $ref: '../schemas/error.yaml'
          examples:
            payload_too_large:
              value:
                code: payload_too_large
                message: Artifact exceeds size limit
    '422':
      description: Unprocessable Entity (invalid checksum/signature/version)
      x-error-codes: [checksum_mismatch, signature_invalid, signature_missing, version_invalid]
      content:
        application/json:
          schema:
            $ref: '../schemas/error.yaml'
          examples:
            checksum_mismatch:
              value:
                code: checksum_mismatch
                message: SHA256 does not match artifact
    '429':
      description: Too Many Requests
      x-error-codes: [rate_limited]
      content:
        application/json:
          schema:
            $ref: '../schemas/error.yaml'
          examples:
            rate_limited:
              value:
                code: rate_limited
                message: Too many requests