From f08938e8290f40e81bc04923b600bb0ec8e9a082 Mon Sep 17 00:00:00 2001
From: Benjamin Ledel <benjamin@schule-plus.com>
Date: Fri, 7 Mar 2025 10:03:39 +0100
Subject: [PATCH] *add documentation
---
docs/docs/analytics_engine.md | 82 +++++++++++++++++++++++++++++++++++
1 file changed, 82 insertions(+)
diff --git a/docs/docs/analytics_engine.md b/docs/docs/analytics_engine.md
index b1b08b4..8773106 100644
--- a/docs/docs/analytics_engine.md
+++ b/docs/docs/analytics_engine.md
@@ -85,3 +85,85 @@ POST /provider/data
| `400 Bad Request` | Invalid request parameters. |
| `401 Unauthorized` | Authentication token is missing or invalid. |
| `500 Internal Server Error` | Server-side error, such as missing provider schema. |
+
+
+
+# Retrieve Analytics Result
+
+```
+POST /provider/results
+```
+
+## Description
+This endpoint retrieves analytics results from the database based on provided filters. It supports pagination and allows filtering by various fields inside the result object, including engine name.
+
+---
+
+## Request Headers
+- `Authorization`: `Basic <token>` (Required) - Authentication token required to access the analytics results.
+
+---
+
+## Request Parameters (JSON Body)
+
+| Parameter | Type | Description |
+| -------------- | -------- | --------------------------------------------------------------------------- |
+| `page` | Integer | (Optional) Page number for pagination (default: 1). |
+| `page_size` | Integer | (Optional) Number of results per page (default: 10). |
+| `name` | String | (Optional) Name of the analytics engine to filter results. |
+| `context_id` | String | (Optional) Unique identifier for the result context. |
+| `created_at` | String | (Optional) Filters results created on a specific date (`YYYY-MM-DD`). |
+| `result.score` | Integer | (Optional) Filters results based on the score value inside the result object. |
+
+---
+
+## Example Request
+
+```json
+{
+ "page": 2,
+ "page_size": 10,
+ "name": "engine_xyz",
+ "context_id": "context-abc123",
+ "created_at": "2025-03-07",
+ "result.score": 88
+}
+```
+
+---
+
+## Response
+
+```json
+{
+ "page": 2,
+ "page_size": 10,
+ "total_pages": 5,
+ "total_results": 50,
+ "results": {
+ "engine_xyz": [
+ {
+ "created_at": "2025-03-07T14:20:30Z",
+ "result": {
+ "score": 88,
+ "status": "completed"
+ },
+ "context_id": "context-abc123",
+ "description": "Analytics result for context-abc123"
+ }
+ ]
+ }
+}
+```
+
+---
+
+## Response Codes
+
+| Status Code | Description |
+| --------------------------- | -------------------------------------------------------- |
+| `200 OK` | Successfully retrieved analytics results. |
+| `400 Bad Request` | Invalid request parameters, such as incorrect date format. |
+| `401 Unauthorized` | Missing or invalid authentication token. |
+| `500 Internal Server Error` | An unexpected error occurred while processing request. |
+
--
GitLab