Documenting error responses

I'm using grunt-aglio to generate HTML documentation from Api Blueprint specification.

I have following questions:

• How can I add text annotation for response with links to external URLs?
• Endpoint has the same functionality für both methods POST and PUT. How can I document it? Is this specification correct:

## Upload file [/files]

Upload new file

### PUT
### POST

+ Request
+ Response