add call via api specs

docs/deploy-pipelines/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Deploy pipelines & API",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Simply deploy your pipelines & call via API."
+  }
+}

docs/deploy-pipelines/call-via-api.md

@@ -0,0 +1,111 @@
+---
+sidebar_position: 1
+---
+
+# Call via API
+
+Once deployed, your pipelines can be called with POST/GET requests.
+
+:::tip Tip
+
+If you've deployed Piper on your own server, replace **piper.my** with your domain name.
+
+:::
+
+## Run pipeline
+
+```bash
+curl --location --request POST 'https://piper.my/api/pipeline-slug/launch' \
+--header 'content-type: application/json' \
+--header 'api-token: [YOUR_API_KEY_HERE]' \
+--data '{
+  "inputs": {
+    name: "Bob Marley",
+    age: 36,
+    died: true
+  }
+}'
+```
+
+:::tip Important
+
+Input type could only primitive: `boolean` | `number` | `string` 
+
+:::
+
+Some pipelines accept JSON as input.
+
+In this case, the JSON must still be serialized into a string.
+
+```json
+{
+  "inputs": {
+    "props": "{ \"name\": \"Bob Marley\", \"age\": 36 }"
+  }
+}
+```
+
+### Images & Media types
+
+There are two ways to send images and other media like videos or audio:
+1. JSON Base64: `data:image/jpeg;base64,...`
+2. Uploading as an artefact.
+
+#### JSON Base64
+
+```bash
+curl --location --request POST 'https://piper.my/api/pipeline-slug/launch' \
+--header 'content-type: application/json' \
+--header 'api-token: [YOUR_API_KEY_HERE]' \
+--data '{
+  "inputs": {
+    image: "data:image/jpeg;base64,..."
+  }
+}'
+```
+
+:::danger Limits
+
+For stability and performance reasons, JSON payloads are limited to 2048 KB.
+For large media files, please upload them as artifacts.
+
+:::
+
+#### Uploading artefact
+
+Piper has its own temporary storage for handling large media files.
+
+```bash
+curl --location --request POST 'https://piper.my/api/artefacts' \
+--header 'api-token: [YOUR_API_KEY_HERE]' \
+-F "file=@/path/to/your/file.jpg"
+```
+
+After the upload, you will receive a URL to access the file.
+
+:::danger Limits
+
+Your file will be deleted automatically after ~48 hours.
+
+:::
+
+## Pipeline status
+
+```bash
+curl --location --request GET 'https://piper.my/api/launches/[LAUNCH_ID]/state' \
+--header 'api-token: [YOUR_API_KEY_HERE]'
+```
+
+Depending on the pipeline type, we recommend polling every 2–5 seconds.
+
+Since outputs in a pipeline are set asynchronously, you need to wait for all the outputs you're expecting.
+
+:::tip Question
+
+> Do you support webhooks or streaming events?
+
+**It's coming very soon!**
+
+Please vote for the [related issue](https://github.com/my-piper/piper/issues/17) to show your support.
+
+:::

docs/tutorial-basics/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Tutorial - Basics",
+  "label": "Pipeline Basics",
   "position": 2,
   "link": {
     "type": "generated-index",

docs/tutorial-extras/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Tutorial - Extras",
+  "label": "Advanced development",
   "position": 3,
   "link": {
     "type": "generated-index"