From 517b6878b785dedf1f8e2feb2945848a11519173 Mon Sep 17 00:00:00 2001
From: Andreas Venturini <andreas.venturini@gmail.com>
Date: Thu, 8 Feb 2024 16:51:11 +0100
Subject: [PATCH] Add documentation for showreels/showreel_media

---
 source/index.html.md | 128 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/source/index.html.md b/source/index.html.md
index e3b9ff3b8ff..345d5500ac0 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -734,6 +734,134 @@ images[].cover | boolean | true if image is a cover image; default: `false`
 images[].copyright | string | image copyright
 
 
+# Showreels
+
+## Get a specific showreel
+
+```shell
+curl "https://www.filmmakers.eu/api/v1/showreels/100" \
+  -H "Authorization: Token token=API_KEY"
+```
+
+> The above command returns JSON structured like this:
+
+```json
+{
+  "id": 100,
+  "showreel_type": "video",
+  "name": "Showreel 2024",
+  "position": 1,
+  "poster_copyright": "Photographer XYZ",
+  "download": true,
+  "showreel_medium_ids": [
+    123456,
+    123457,
+    123458,
+    123459,
+    123460
+  ],
+  "poster": "https://imgproxy.filmmakers.eu/8f7c74be-c696-11ee-85a8-4781e0bae8b1.jpeg"
+}
+
+```
+
+This endpoint retrieves a specific showreel.
+
+### HTTP Request
+
+`GET https://www.filmmakers.eu/api/v1/showreels/<ID>`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+ID | The ID of the showreel to retrieve (refer to the `showreel_ids` array field from actor_profiles endpoint to obtain these ids)
+
+### Response fields
+
+See example response to the right for an overview of included fields
+
+Field | Type | Description
+--------- | ------- | -----------
+id | integer | ID of the showreel
+showreel_type | string | either `video` or `audio`
+name | string | name of the showreel
+position | integer | The position of the showreel on Filmmakers
+poster | string | Image url to the showreel poster/thumb
+poster_copyright | string | Copyright for the showreel poster/thumb
+download | boolean | Whether the download option is active on Filmmakers
+showreel_medium_ids| array | IDs of showreel media contained in the showreel (see `shoreel_media` endpoint below)
+
+# Showreel Media
+
+## Get specific showreel media
+
+```shell
+curl "https://www.filmmakers.eu/api/v1/showreel_media/123456" \
+  -H "Authorization: Token token=API_KEY"
+```
+
+> The above command returns JSON structured like this:
+
+```json
+{
+  "id": 123456,
+  "type": "ShowreelVideo",
+  "name": "Faking Bullshit",
+  "director": "Alexander Schubert",
+  "role": "Rocky",
+  "year": 2019,
+  "download": true,
+  "duration": "171.6",
+  "skills": [
+    "languages/deutsch"
+  ],
+  "vita_entry_id": 300,
+  "skill": "languages/deutsch",
+  "picture": "https://imgproxy.filmmakers.eu/8f7c74be-c696-11ee-85a8-4781e0bae8b1.jpeg",
+  "asset": null,
+  "proxies": {
+    "sd": "https://static.filmmakers.eu/production/0fd099dc-c698-11ee-93cb-cb381089a4e7.mp4",
+    "hd": "https://static.filmmakers.eu/production/107a9e6e-c698-11ee-8895-f34d7095f1f5.mp4",
+    "full_hd": "https://static.filmmakers.eu/production/109d0832-c698-11ee-b7b8-fb95fd1a375c.mp4"
+  }
+}
+
+```
+
+This endpoint retrieves specific showreel media.
+
+### HTTP Request
+
+`GET https://www.filmmakers.eu/api/v1/showreel_media/<ID>`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+ID | The ID of the showreel media to retrieve (refer to the `showreel_medium_ids` array field from showreels endpoint to obtain these ids)
+
+### Response fields
+
+See example response to the right for an overview of included fields
+
+Field | Type | Description
+--------- | ------- | -----------
+id | integer | ID of the video or audio
+type | string | either `ShowreelVideo` (for videos) or `ShowreelAudio` (for audios)
+name | string | Name of the video or audio
+director | string | Name of the director linked to the medium (if any)
+role | string| Name of the role linked to the medium (if any)
+year | integer | Year of the medium (if any)
+download | boolean | Whether the download option is active on Filmmakers
+duration | float | Duration in seconds
+skills | array | Links to skills from actor profile attributes, in the format of `NAME#VALUE`, e.g. `languages#deutsch` or `dialects#berlinerisch`
+skill | string | Deprecated, please use `skills`
+vita_entry_id | integer | ID of vita entry (credit) if any
+picture | string | Image url to the thumb
+asset | string | Only filled in for type `ShowreelAudio`, may contain codecs `AAC` or `MP3`
+proxies | array | Only filled in for type `ShowreelVideo`. Link to transcoded proxies (MP4, H.264). May contain up to three proxies: `sd` (480p), `hd` (720p) and `full_hd` (1080p). Depending on the quality of the source file only one `sd` and/or `hd` might be present.
+
 # Attributes
 
 ## Get all attributes