[IIIF-203] Updated bitstreams contract

Author: AdamF42

bitstreams.md

@@ -117,6 +117,49 @@ The supported **Request Headers** are:
 * Range: not implemented yet. Provide support to partial content download
 * If-None-Match: not implemented yet. Support for cache control
 
+### Presigned URL
+
+**GET /api/core/bitstreams/<:uuid>/signedurl**
+
+This endpoint returns a presigned URL that allows direct, temporary access to the bitstream content stored in the configured storage backend (e.g., S3). Clients can use this URL to download the bitstream without passing through the DSpace server, improving performance and offloading bandwidth.
+
+#### Security
+
+- Requires READ permission on the specified bitstream (`hasPermission(#uuid, 'BITSTREAM','READ')`).
+
+
+#### Response
+
+A JSON object containing:
+
+- `presignedUrl`: The generated presigned URL granting temporary access.
+- `bitstreamId`: The UUID of the bitstream.
+- `filename`: The user-friendly name of the bitstream (if available).
+
+Example response body:
+
+```json
+{
+  "presignedUrl": "https://bucket.s3.amazonaws.com/object?X-Amz-Algorithm=...",
+  "bitstreamId": "8d33bdfb-e7ba-43e6-a93a-f445b7e8a1e2",
+  "filename": "example.pdf"
+}
+```
+
+
+#### Error Responses
+
+- **404 Not Found**: If the bitstream with the given UUID does not exist or a presigned URL cannot be generated.
+- **401 Unauthorized**: If the requester is anonymous  and the bitstream does not have read permissions.
+- **403 Forbidden**: If the requester lacks sufficient permissions to read the bitstream.
+- **500 Internal Server Error**: If an unexpected error occurs during processing.
+
+
+#### Notes
+
+- The expiration time of the presigned URL is configurable via the DSpace configuration property `assetstore.s3.presigned.url.expiration.seconds`.
+- This URL is intended for temporary direct access and should be used promptly before expiration.
+
 ### Main Thumbnail
 **/api/core/bitstreams/<:uuid>/thumbnail**