OSVauco/docs/CUSTOMER_API.md

# 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 |