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.

{
  "status": "ok"
}

Example:

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:

{
    "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):

{
    "response": "The project is on track. The CI/CD pipeline is complete, but the Dialogflow agent setup is currently blocked."
}

Example curl Request:

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):

{
    "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