GITBOOK-115: No subject

Author: alexjustesen

README.md

@@ -8,7 +8,7 @@ description: >-
 # Introduction
 
 {% hint style="info" %}
-Docs are up to date through version: `v1.0.1`
+Docs are up to date through version: `v1.1.0`
 {% endhint %}
 
 <figure><img src=".gitbook/assets/dashboard.png" alt=""><figcaption></figcaption></figure>

SUMMARY.md

@@ -51,7 +51,8 @@
 
 ## 🖥️ API
 
-* [Latest Result](api/latest-result.md)
+* [v1](api/v1.md)
+* [Latest Result (deprecated)](api/latest-result.md)
 
 ## 🤹 Contributing
 

api/v1.md

@@ -0,0 +1,145 @@
+# v1
+
+### Authorization
+
+A "Bearer Token" is required to authenticate into the API, you can generate tokens for your user account on `/admin/api-tokens`.
+
+***
+
+### Get result
+
+<pre class="language-bash"><code class="lang-bash"><strong>curl localhost/api/v1/results/{id}
+</strong>   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+</code></pre>
+
+#### Parameters
+
+* `id`- record ID of the result to get
+
+#### Responses
+
+* 200: OK
+* 404: Result not found
+
+
+
+***
+
+### List result
+
+```bash
+curl localhost/api/v1/results
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere
+```
+
+#### Filtering
+
+You can filter the results response by the fields: `ping`, `download`, `upload`, `healthy`, `status`, `scheduled`, `created_at` and `updated_at`.
+
+Example: filter dates in a range
+
+```bash
+curl localhost/api/v1/results?filter[created_at]=>=2024-01-01&filter[created_at]=<=2024-12-31
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+Example: filter for only unhealthy results
+
+```bash
+curl localhost/api/v1/results?filter[healthy]=false
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+Example: filter for "failed" and "skipped" results
+
+```bash
+curl localhost/api/v1/results?filter[status]=failed,skipped
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+#### Sorting
+
+You can sort the results response by the fields: `ping`, `download`, `upload`, `created_at` or `updated_at`. Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.
+
+```bash
+curl localhost/api/v1/results?sort=-created_at
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+#### Responses
+
+* 200: OK
+* 422: Unprocessable Entity (validation probably failed, see logs)
+
+
+
+***
+
+### Get latest result
+
+```bash
+curl localhost/api/v1/results/latest
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+#### Responses
+
+* 200: OK
+* 404: No result found
+
+
+
+***
+
+### Data Dictionary
+
+The data structure returned mimic the `results` table but includes the addition of `download_bits`, `upload_bits`, `download_bits_human` and `upload_bits_human`.
+
+```json
+{
+  "data": {
+    "id": 1009,
+    "service": "ookla",
+    "ping": 7.448,
+    "download": 167270969,
+    "upload": 115884569,
+    "download_bits": 1338167752,
+    "upload_bits": 927076552,
+    "download_bits_human": "1.34 Gbps",
+    "upload_bits_human": "927.08 Mbps",
+    "benchmarks": null,
+    "healthy": null,
+    "status": "completed",
+    "scheduled": true,
+    "comments": null,
+    "data": {
+    },
+    "created_at": "2025-01-13 16:37:00",
+    "updated_at": "2025-01-13 16:37:17"
+  }
+}
+```
+
+
+
+***
+
+### FAQ
+
+<details>
+
+<summary>Can I create, update or delete results through the API?</summary>
+
+No, not at this time its read-only.
+
+</details>
+
+
+