From ea16a0616f842723c1878975aa9b0c21f65dd7af Mon Sep 17 00:00:00 2001
From: FireMasterK <20838718+FireMasterK@users.noreply.github.com>
Date: Fri, 3 Sep 2021 21:37:24 +0530
Subject: [PATCH] Add initial API documentation.

---
 content/docs/api-documentatoin/index.md | 103 ++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 content/docs/api-documentatoin/index.md

diff --git a/content/docs/api-documentatoin/index.md b/content/docs/api-documentatoin/index.md
new file mode 100644
index 0000000..4be32da
--- /dev/null
+++ b/content/docs/api-documentatoin/index.md
@@ -0,0 +1,103 @@
+---
+title: "API Documentation"
+weight: 4
+summary: A guide on how to use Piped's API.
+---
+
+## API Servers
+
+A list of public instances can be found at https://github.com/TeamPiped/Piped/wiki/Instances
+
+To keep up-to date with the instances list, you are expected to dynamically parse it.
+
+An example on how this can be done is available at https://github.com/TeamPiped/Piped/blob/85e2296dc410fd20375d623465900c55b5483da9/src/components/Preferences.vue#L202-L221
+
+## Base URL
+
+For all endpoints in this documentation, you will have to use an API url as a prefix. For example, the official instance's base URL would be https://pipedapi.kavin.rocks
+
+## Unauthenticated Endpoints
+
+These endpoints work un-authenticated, and you're highly discouraged to send an `Authorization` header for these endpoints.
+
+### /streams/:videoId
+
+Parameters:
+
+-   `videoId`: The video ID of the YouTube video you want to get information about.
+
+Response:
+
+```json
+{
+	"audioStreams": [
+		{
+			"bitrate": 0, // The bitrate of the audio stream in bytes
+			"codec": "mp4a.40.5", // The codec of the audio stream
+			"format": "M4A", // The format of the audio stream
+			"indexEnd": 0, // Useful for creating dash streams
+			"indexStart": 0, // Useful for creating dash streams
+			"initStart": 0, // Useful for creating dash streams
+			"initEnd": 0, // Useful for creating dash streams
+			"mimeType": "audio/mp4", // The mime type of the audio stream
+			"quality": "48 kbps", // The quality of the audio stream
+			"url": "https://pipedproxy-bom.kavin.rocks/videoplayback?...", // The stream's URL
+			"videoOnly": false // Whether or not the stream is video only
+		}
+	], // The audio streams of the video
+	"dash": null, // The dash manifest URL, to be used if not null (for OTF streams)
+	"description": "", // The description of the video
+	"dislikes": 0, // The number of dislikes the video has
+	"duration": 0, // The duration of the video in seconds
+	"hls": null, // The hls manifest URL, to be used for Livestreams,
+    "lbryId": "", // The lbry id of the video, if available
+    "likes": 0, // The number of likes the video has
+    "livestream": false, // Whether or not the video is a livestream
+    "proxyUrl": "https://pipedproxy-bom.kavin.rocks", // The proxy url to be used for rewrites
+    "relatedStreams": [
+        {
+            "duration": 0, // The duration of the related video in seconds
+            "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the related video
+            "title": "", // The title of the related video
+            "uploadedDate": "3 months ago", // The date the related video was uploaded
+            "uploaderUrl": "/channel/...", // The URL of the channel of the related video
+            "uploaderVerified": true, // Whether or not the channel of the related video is verified
+            "url": "/watch?v=..." // The URL of the related video
+            "views": 0 // The number of views the related video has
+        }
+    ], // A list of related streams
+    "subtitles": [
+        {
+            "autoGenerated": false, // Whether or not the subtitle was auto-generated
+            "code": "en", // The language code of the subtitle
+            "mimeType": "application/ttml+xml", // The mime type of the subtitle
+            "name": "English", // The name of the subtitle
+            "url": "https://pipedproxy-bom.kavin.rocks/api/timedtext?..." // The URL of the subtitle
+        }
+    ], // A list of subtitles
+    "thumbnailUrl": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the video
+    "title": "", // The title of the video
+    "uploadedDate": "2021-01-01", // The date the video was uploaded
+    "uploader": "", // The name of the channel of the video
+    "uploaderUrl": "/channel/...", // The URL of the channel of the video
+    "videoStreams": [
+        {
+            "bitrate": 0, // The bitrate of the video stream in bytes
+            "codec": "avc1.64002a", // The codec of the video stream
+            "format": "MPEG_4", // The format of the video stream
+            "fps": 30, // The frames per second of the video stream
+            "height": 720, // The height of the video stream
+            "indexEnd": 0, // Useful for creating dash streams
+            "indexStart": 0, // Useful for creating dash streams
+            "initStart": 0, // Useful for creating dash streams
+            "initEnd": 0, // Useful for creating dash streams
+            "mimeType": "video/mp4", // The mime type of the video stream
+            "quality": "720p", // The quality of the video stream
+            "url": "https://pipedproxy-bom.kavin.rocks/videoplayback?...", // The stream's URL
+            "videoOnly": false // Whether or not the stream is video only
+            "width": 1280 // The width of the video stream
+        }
+    ], // The video streams of the video
+    "views": 0 // The number of views the video has
+}
+```