docs: Create API documentation and update TODO
- 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
parent
05030edf61
commit
449edf37b8
199
docs/CUSTOMER_API.md
Normal file
199
docs/CUSTOMER_API.md
Normal 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 |
|
||||
|
|
@ -6,9 +6,9 @@
|
|||
|
||||
## 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`.
|
||||
- [ ] 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).
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user