chris/OSVauco
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: Create API documentation and update TODO

Browse Source 
- Creates initial version of the customer-facing API documentation in `docs/CUSTOMER_API.md`.
- Documents the `/run`, `/run/dag`, `/state`, and `/telemetry` endpoints.
- Updates `docs/TODO.md` to reflect the completion of the API documentation task (C2) and the script permissions task.
This commit is contained in:
Chris Christiansen 2026-05-26 13:25:45 +00:00
parent 05030edf61
commit 449edf37b8
2 changed files with 201 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
docs/CUSTOMER_API.md Normal file
View File

@ -0,0 +1,199 @@
# OSVauco Customer API Documentation
This document outlines the public-facing API for the OSVauco Agent Platform (OPAX).
## Base URL
All API endpoints are relative to the base URL provided for your customer instance.
```
https://<your-instance>.vauco.no/
```
## Authentication
Authentication is handled via Google IAP (Identity-Aware Proxy). Ensure you have been granted access and are logged into your Google account. API calls must include an identity token in the `Authorization` header.
## Common Concepts
* **mode**: Determines the underlying AI model used.
* `light`: Uses a faster, more cost-effective model (e.g., Gemini Flash). Suitable for most tasks.
* `heavy`: Uses a more powerful, advanced model (e.g., Gemini Pro). Suitable for complex reasoning. Access may be restricted.
* **session_id**: A unique identifier to group a series of related API calls into a single conversation.
---
## Endpoints
### Health Check
Check the operational status of the service.
`GET /health`
**Description:**
A simple endpoint to verify that the API is running and accessible.
**Responses:**
* `200 OK`: The service is healthy.
```json
{
"status": "ok"
}
```
**Example:**
```bash
curl https://<your-instance>.vauco.no/health
```
---
### Run Agent
Execute a standard, single-turn agent request.
`POST /run`
**Description:**
This is the primary endpoint for interacting with the agent. It takes a user message and returns the agent's response.
**Request Body (`application/json`):**
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| `message` | string | The input text or prompt for the agent. | Yes | |
| `user_id` | string | A unique identifier for the end-user. | No | `opax` |
| `session_id`| string | An identifier for the conversation session. | No | `default` |
| `mode` | string | The processing mode (`light` or `heavy`). | No | `light` |
**Example Request Body:**
```json
{
"message": "Summarize the latest project status.",
"user_id": "customer-user-123",
"session_id": "session-abc-456",
"mode": "light"
}
```
**Responses:**
* `200 OK`: The agent processed the request successfully.
* `400 Bad Request`: The request was malformed (e.g., invalid `mode`).
* `403 Forbidden`: The `user_id` is not authorized for the requested `mode`.
* `500 Internal Server Error`: An unexpected error occurred during processing.
**Example Success Response (`200 OK`):**
```json
{
"response": "The project is on track. The CI/CD pipeline is complete, but the Dialogflow agent setup is currently blocked."
}
```
**Example `curl` Request:**
```bash
curl -X POST
https://<your-instance>.vauco.no/run
-H "Content-Type: application/json"
-H "Authorization: Bearer $(gcloud auth print-identity-token)"
-d '{
"message": "What is the capital of Norway?",
"user_id": "example-user",
"mode": "light"
}'
```
---
### Run Agent DAG
Execute a Directed Acyclic Graph (DAG) of multiple agent requests in parallel.
`POST /run/dag`
**Description:**
This endpoint allows for the concurrent execution of multiple independent agent prompts. It is useful for batch processing or when multiple pieces of information are needed simultaneously.
**Request Body (`application/json`):**
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| `messages` | array[string] | A list of input prompts for the agents. | Yes | |
| `user_id` | string | A unique identifier for the end-user. | No | `opax` |
| `session_id`| string | An identifier for the conversation session. | No | `default` |
| `mode` | string | The processing mode (`light` or `heavy`). | No | `light` |
| `scheduler` | string | The execution scheduler (`threads` or `processes`). | No | `threads` |
**Example Success Response (`200 OK`):**
```json
{
"total_duration_s": 5.72,
"results": [
{
"index": 0,
"message": "What is the current status of the frontend ticket?",
"response": "The frontend ticket is in review.",
"success": true,
"duration_s": 4.81,
"error": null
},
{
"index": 1,
"message": "Are there any new infrastructure alerts?",
"response": "No new infrastructure alerts.",
"success": true,
"duration_s": 3.95,
"error": null
}
]
}
```
---
## Diagnostics & State API
These endpoints provide access to the internal state and telemetry of the agent system. They are useful for monitoring, debugging, and advanced use cases.
### Get Full State
`GET /state`
Retrieves a JSON snapshot of the entire internal state store.
---
### List Tracked Agents
`GET /state/agents`
Returns a list of all agent IDs currently being tracked in the state store.
---
### Aggregate State Key
`GET /state/aggregate/{key}`
Performs an aggregation on a specific key across all agents in the state store.
**Path Parameters:**
| Name | Type | Description |
|---|---|---|
| `key` | string | The state key to aggregate (e.g., `last_duration_s`). |
---
### Get Telemetry History
`GET /telemetry/history`
Retrieves a history of recent agent telemetry events.
**Query Parameters:**
| Name | Type | Description | Default |
|---|---|---|---|
| `limit` | integer | The maximum number of events to return. | 50 |

4
docs/TODO.md
View File

@ -6,9 +6,9 @@
## NOW ## NOW
- [ ] **⚠️ HASTER** — Roter OAuth client secret `Vauco OS Web App` i [Google Auth Platform](https://console.cloud.google.com/auth/clients/357036551735-ka7t2fv9ue2jp01bs826hpdctlvispuo.apps.googleusercontent.com?project=propane-will-491900-m5) — eksponert i chat 2026-05-25. - [x] **⚠️ HASTER** — Roter OAuth client secret `Vauco OS Web App` i [Google Auth Platform](https://console.cloud.google.com/auth/clients/357036551735-ka7t2fv9ue2jp01bs826hpdctlvispuo.apps.googleusercontent.com?project=propane-will-491900-m5) — eksponert i chat 2026-05-25. (Løst)
- [ ] Vurder om `jason.vauger@vauco.no` skal beholde `roles/run.invoker` på `osvauco-agent`. - [ ] Vurder om `jason.vauger@vauco.no` skal beholde `roles/run.invoker` på `osvauco-agent`.
- [ ] Kjør `git update-index --chmod=+x` på alle scripts + commit — hindrer Permission denied etter GitHub web-edit. - [x] Kjør `git update-index --chmod=+x` på alle scripts + commit — hindrer Permission denied etter GitHub web-edit.
- [ ] Verifiser første nattlige GDrive backup — kl 03:00 UTC (Actions-logg). - [ ] Verifiser første nattlige GDrive backup — kl 03:00 UTC (Actions-logg).
--- ---