From 60a91c1163579cb2bf4779e8fd6177ffec22f351 Mon Sep 17 00:00:00 2001
From: diegosouzapw <diegosouza.pw@gmail.com>
Date: Thu, 28 May 2026 13:59:30 -0300
Subject: [PATCH] feat(agent-skills): document rotate + metrics endpoints in
 omni-providers (GAP-E)

---
 skills/omni-providers/SKILL.md | 50 ++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/skills/omni-providers/SKILL.md b/skills/omni-providers/SKILL.md
index bd16e7b995..0dd1dfab38 100644
--- a/skills/omni-providers/SKILL.md
+++ b/skills/omni-providers/SKILL.md
@@ -177,3 +177,53 @@ curl https://localhost:20128/api/provider-models \
 ## Payloads
 
 See the full OpenAPI specification at `GET /api/openapi/spec` or `docs/reference/openapi.yaml` for detailed request/response schemas.
+
+<!-- skill:custom-start -->
+## Additional endpoints
+
+### POST /api/providers/{id}/refresh
+
+Rotate / refresh OAuth tokens or re-validate credentials for a provider connection. Useful after token expiration or when credentials need to be renewed without deleting the connection.
+
+```bash
+curl -X POST https://localhost:20128/api/providers/{id}/refresh \
+  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+### GET /api/provider-metrics
+
+Retrieve aggregated usage and performance metrics for all provider connections (request counts, error rates, latency percentiles, token usage). Used by dashboards and Auto-Combo scoring.
+
+```bash
+curl https://localhost:20128/api/provider-metrics \
+  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
+```
+
+**Response example:**
+```json
+{
+  "providers": [
+    {
+      "id": "my-openai",
+      "requestCount": 1240,
+      "errorRate": 0.02,
+      "p50LatencyMs": 340,
+      "p99LatencyMs": 1200,
+      "tokensIn": 500000,
+      "tokensOut": 250000
+    }
+  ]
+}
+```
+
+### GET /api/providers/health-matrix
+
+Returns a health-matrix view of all providers with per-connection status, circuit-breaker state, and cooldown expiry. Useful for debugging routing decisions.
+
+```bash
+curl https://localhost:20128/api/providers/health-matrix \
+  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
+```
+<!-- skill:custom-end -->