From 4bcd2b41674da21657361b04e2ef2872de14ddd3 Mon Sep 17 00:00:00 2001 From: zenfun Date: Wed, 31 Dec 2025 18:01:56 +0800 Subject: [PATCH] docs(swagger): add generated swagger API documentation Add auto-generated Swagger/OpenAPI documentation files for the EZ-API Control Plane. These files are generated by swaggo/swag and provide comprehensive API documentation including: - All admin endpoints (alerts, API keys, bindings, masters, etc.) - Master/tenant endpoints for token management and stats - Internal endpoints for DP-CP communication - Authentication schemes (AdminAuth, MasterAuth) - Request/response schema definitions --- docs/swagger/docs.go | 6244 +++++++++++++++++++++++++++++++++++++ docs/swagger/swagger.json | 6220 ++++++++++++++++++++++++++++++++++++ docs/swagger/swagger.yaml | 4031 ++++++++++++++++++++++++ 3 files changed, 16495 insertions(+) create mode 100644 docs/swagger/docs.go create mode 100644 docs/swagger/swagger.json create mode 100644 docs/swagger/swagger.yaml diff --git a/docs/swagger/docs.go b/docs/swagger/docs.go new file mode 100644 index 0000000..d764076 --- /dev/null +++ b/docs/swagger/docs.go @@ -0,0 +1,6244 @@ +// Package swagger Code generated by swaggo/swag. DO NOT EDIT +package swagger + +import "github.com/swaggo/swag" + +const docTemplate = `{ + "schemes": {{ marshal .Schemes }}, + "swagger": "2.0", + "info": { + "description": "{{escape .Description}}", + "title": "{{.Title}}", + "termsOfService": "http://swagger.io/terms/", + "contact": { + "name": "API Support", + "url": "http://www.swagger.io/support", + "email": "support@swagger.io" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "{{.Version}}" + }, + "host": "{{.Host}}", + "basePath": "{{.BasePath}}", + "paths": { + "/about": { + "get": { + "description": "Returns system metadata for display on an about page", + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "Get system information", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AboutResponse" + } + } + } + } + }, + "/admin/alerts": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List system alerts with optional filters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List alerts", + "parameters": [ + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "offset", + "name": "offset", + "in": "query" + }, + { + "type": "string", + "description": "filter by status (active, acknowledged, resolved, dismissed)", + "name": "status", + "in": "query" + }, + { + "type": "string", + "description": "filter by severity (info, warning, critical)", + "name": "severity", + "in": "query" + }, + { + "type": "string", + "description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down, traffic_spike)", + "name": "type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.ListAlertsResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a new system alert", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create alert", + "parameters": [ + { + "description": "Alert data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.CreateAlertRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/stats": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get alert count statistics by status and severity", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Alert statistics", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertStats" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/thresholds": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get current alert threshold configuration for traffic spike detection", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get alert thresholds", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertThresholdView" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update alert threshold configuration for traffic spike detection", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update alert thresholds", + "parameters": [ + { + "description": "Threshold configuration", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateAlertThresholdsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertThresholdView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a single alert by ID", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Dismiss an alert (soft delete)", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Dismiss alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/{id}/ack": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Mark an alert as acknowledged", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Acknowledge alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Ack data", + "name": "request", + "in": "body", + "schema": { + "$ref": "#/definitions/internal_api.AckAlertRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/{id}/resolve": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Mark an alert as resolved", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Resolve alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/api-keys": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List API keys with optional filters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List API keys", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "filter by group_id", + "name": "group_id", + "in": "query" + }, + { + "type": "string", + "description": "filter by status (active, suspended, auto_disabled, manual_disabled)", + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create an API key for a provider group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create an API key", + "parameters": [ + { + "description": "API key payload", + "name": "key", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/api-keys/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete or status update for api keys", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch api keys", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/api-keys/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get an API key by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get API key", + "parameters": [ + { + "type": "integer", + "description": "APIKey ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update an API key", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update API key", + "parameters": [ + { + "type": "integer", + "description": "APIKey ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "API key payload", + "name": "key", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete an API key", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete API key", + "parameters": [ + { + "type": "integer", + "description": "APIKey ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/apikey-stats/summary": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Aggregate APIKey success/failure stats across all provider groups", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "APIKey stats summary (admin)", + "parameters": [ + { + "type": "integer", + "description": "Start time (unix seconds)", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "End time (unix seconds)", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.APIKeyStatsSummaryResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/bindings": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all configured bindings", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List bindings", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by namespace/public_model", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a new (namespace, public_model) binding to a provider group and selector", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create a new binding", + "parameters": [ + { + "description": "Binding Info", + "name": "binding", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.BindingDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/bindings/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete or status update for bindings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch bindings", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/bindings/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a binding by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get a binding", + "parameters": [ + { + "type": "integer", + "description": "Binding ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update an existing binding", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update a binding", + "parameters": [ + { + "type": "integer", + "description": "Binding ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Binding Info", + "name": "binding", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.BindingDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a binding by id and rebuild bindings snapshot", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete a binding", + "parameters": [ + { + "type": "integer", + "description": "Binding ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/dashboard/summary": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns aggregated metrics for dashboard display including requests, tokens, latency, masters, keys, and provider keys statistics", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Dashboard summary", + "parameters": [ + { + "type": "string", + "description": "time period: today, week, month, all", + "name": "period", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.DashboardSummaryResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/features": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns all feature flags stored in Redis (meta:features)", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List feature flags", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates selected feature flags (meta:features). Values are stored as strings.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update feature flags", + "parameters": [ + { + "description": "Feature map", + "name": "request", + "in": "body", + "required": true, + "schema": { + "type": "object" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/keys/{id}/access": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns key default_namespace and namespaces", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get key access settings", + "parameters": [ + { + "type": "integer", + "description": "Key ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates key default_namespace and namespaces and syncs to Redis", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update key access settings", + "parameters": [ + { + "type": "integer", + "description": "Key ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Access settings", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateAccessRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/logs": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List request logs with basic filtering/pagination. Returns full log records including request_body.", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List logs (admin)", + "parameters": [ + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "offset", + "name": "offset", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + }, + { + "type": "integer", + "description": "key id", + "name": "key_id", + "in": "query" + }, + { + "type": "string", + "description": "route group", + "name": "group", + "in": "query" + }, + { + "type": "string", + "description": "model", + "name": "model", + "in": "query" + }, + { + "type": "integer", + "description": "status code", + "name": "status_code", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.ListLogsResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete logs before a given timestamp with optional filters", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete logs (admin)", + "parameters": [ + { + "description": "Delete filters", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.DeleteLogsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.DeleteLogsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/logs/stats": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Aggregate log stats with basic filtering. Use group_by param for grouped statistics (model/day/month/hour/minute). Without group_by returns LogStatsResponse; with group_by returns GroupedStatsResponse. Note: minute-level aggregation is limited to 6-hour time ranges.", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Log stats (admin)", + "parameters": [ + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + }, + { + "enum": [ + "model", + "day", + "month", + "hour", + "minute" + ], + "type": "string", + "description": "group by dimension: model, day, month, hour, minute. Returns GroupedStatsResponse when specified.", + "name": "group_by", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Grouped stats (when group_by is specified)", + "schema": { + "$ref": "#/definitions/internal_api.GroupedStatsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/logs/webhook": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns current webhook notification config", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get log webhook config", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates webhook notification config", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update log webhook config", + "parameters": [ + { + "description": "Webhook config", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all master tenants", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List masters", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/group", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterView" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a new master account (tenant)", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create a new master tenant", + "parameters": [ + { + "description": "Master Info", + "name": "master", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.CreateMasterRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete or status update for masters", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch masters", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a master tenant by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update master fields; optionally propagate group to existing keys", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateMasterRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Suspends a master and revokes all existing keys by bumping epoch and syncing to Redis", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete (revoke) master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/access": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns master default_namespace and namespaces", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get master access settings", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates master default_namespace and namespaces; optionally propagate to existing keys", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update master access settings", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Access settings", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateAccessRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/keys": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Issue a new access token (child key) for a specified master. The key still belongs to the master; issuer is recorded as admin for audit.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Issue a child key on behalf of a master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Key Request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.IssueChildKeyRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/manage": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Freeze or unfreeze a master tenant", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Manage master status", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Action", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.ManageMasterRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/realtime": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Return realtime counters for the specified master", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Master realtime stats (admin)", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterRealtimeView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/check": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Checks models.dev commit SHA for a ref and indicates whether refresh is needed (does not apply changes)", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Check model registry upstream version", + "parameters": [ + { + "description": "optional override ref", + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/internal_api.refreshModelRegistryRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.ModelRegistryCheckResult" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/refresh": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Fetches models.dev, computes per-binding capabilities, and updates Redis meta:models", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Refresh model registry from models.dev", + "parameters": [ + { + "description": "optional override ref", + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/internal_api.refreshModelRegistryRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/rollback": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Rollback meta:models to previous cached last-good version", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Rollback model registry", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/status": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns Redis meta and local last-good cache info for model capability registry", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get model registry status", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.ModelRegistryStatus" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/models": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a list of all registered models", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List all models", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/kind", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Model" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Register a supported model with its capabilities", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Register a new model", + "parameters": [ + { + "description": "Model Info", + "name": "model", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ModelDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Model" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/models/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete for models", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch models", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/models/{id}": { + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update an existing model's configuration", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update a model", + "parameters": [ + { + "type": "integer", + "description": "Model ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Model Info", + "name": "model", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ModelDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Model" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a model by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete a model", + "parameters": [ + { + "type": "integer", + "description": "Model ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/namespaces": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all namespaces", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List namespaces", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/description", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a namespace for bindings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create namespace", + "parameters": [ + { + "description": "Namespace payload", + "name": "namespace", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.NamespaceRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/namespaces/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a namespace by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get namespace", + "parameters": [ + { + "type": "integer", + "description": "Namespace ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update a namespace", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update namespace", + "parameters": [ + { + "type": "integer", + "description": "Namespace ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update payload", + "name": "namespace", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateNamespaceRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a namespace and its bindings", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete namespace", + "parameters": [ + { + "type": "integer", + "description": "Namespace ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/operation-logs": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List admin operation logs", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List operation logs", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by actor/method/path", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.OperationLogView" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/provider-groups": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all provider groups", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List provider groups", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/type", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a provider group definition", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create a provider group", + "parameters": [ + { + "description": "Provider group payload", + "name": "group", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/provider-groups/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a provider group by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get provider group", + "parameters": [ + { + "type": "integer", + "description": "ProviderGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update a provider group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update provider group", + "parameters": [ + { + "type": "integer", + "description": "ProviderGroup ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Provider group payload", + "name": "group", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a provider group and its api keys/bindings", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete provider group", + "parameters": [ + { + "type": "integer", + "description": "ProviderGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/realtime": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Return aggregated realtime counters across all masters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "System-level realtime stats (admin)", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.SystemRealtimeView" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/stats": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Aggregate request stats across all masters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Usage stats (admin)", + "parameters": [ + { + "type": "string", + "description": "today|week|month|all", + "name": "period", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AdminUsageStatsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/sync/snapshot": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Force full synchronization of DB state to Redis", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Force sync snapshot", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/auth/whoami": { + "get": { + "security": [ + { + "AdminAuth": [] + }, + { + "MasterAuth": [] + } + ], + "description": "Returns the identity of the authenticated user based on the Authorization header.\nSupports Admin Token, Master Key, and Child Key (API Key) authentication.\n\nResponse varies by token type:\n- Admin Token: {\"type\": \"admin\", \"role\": \"admin\"}\n- Master Key: {\"type\": \"master\", \"id\": 1, \"name\": \"...\", ...}\n- Child Key: {\"type\": \"key\", \"id\": 5, \"master_id\": 1, \"issued_by\": \"master\", ...}", + "produces": [ + "application/json" + ], + "tags": [ + "auth" + ], + "summary": "Get current identity", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.WhoamiResponse" + } + }, + "401": { + "description": "Invalid or missing token", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/internal/alerts/report": { + "post": { + "description": "Internal endpoint for Data Plane to report alerts to Control Plane", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Report alerts from DP", + "parameters": [ + { + "description": "Alerts to report", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/internal/apikey-stats/flush": { + "post": { + "description": "Internal endpoint for flushing accumulated APIKey stats from DP to CP database", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Flush API key stats", + "parameters": [ + { + "description": "Stats to flush", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.apiKeyStatsFlushRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/internal/stats/flush": { + "post": { + "description": "Internal endpoint for flushing accumulated key usage stats from DP to CP database", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Flush key stats", + "parameters": [ + { + "description": "Stats to flush", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.statsFlushRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/logs": { + "post": { + "description": "Internal endpoint for ingesting logs from Balancer", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "system" + ], + "summary": "Ingest logs", + "parameters": [ + { + "description": "Log Record", + "name": "log", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.LogRecord" + } + } + ], + "responses": { + "202": { + "description": "Accepted", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/status": { + "get": { + "description": "Returns public runtime status information without sensitive data", + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "Get system status", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.StatusResponse" + } + } + } + } + }, + "/v1/logs": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "List request logs for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "List logs (master)", + "parameters": [ + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "offset", + "name": "offset", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + }, + { + "type": "string", + "description": "model", + "name": "model", + "in": "query" + }, + { + "type": "integer", + "description": "status code", + "name": "status_code", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.ListMasterLogsResponse" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/logs/stats": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Aggregate request log stats for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Log stats (master)", + "parameters": [ + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.LogStatsResponse" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/realtime": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Return realtime counters for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Master realtime stats", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterRealtimeView" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/self": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Returns master metadata for the authenticated master key", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Get current master info", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/stats": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Aggregate request stats for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Usage stats (master)", + "parameters": [ + { + "type": "string", + "description": "today|week|month|all", + "name": "period", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterUsageStatsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/tokens": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "List child keys issued under the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "List child keys", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by group/scopes/namespaces/status", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.TokenView" + } + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Issue a new access token (child key) for the authenticated master", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Issue a child key", + "parameters": [ + { + "description": "Key Request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.IssueChildKeyRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/tokens/{id}": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Get a child key by id under the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Get child key", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.TokenView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Update token scopes/status under the authenticated master", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Update child key", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateTokenRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.TokenView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Suspends a child key under the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Delete (revoke) child key", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + } + }, + "definitions": { + "gin.H": { + "type": "object", + "additionalProperties": {} + }, + "github_com_ez-api_ez-api_internal_dto.APIKeyDTO": { + "type": "object", + "properties": { + "access_token": { + "type": "string" + }, + "account_id": { + "type": "string" + }, + "api_key": { + "type": "string" + }, + "auto_ban": { + "type": "boolean" + }, + "ban_reason": { + "type": "string" + }, + "ban_until": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "group_id": { + "type": "integer" + }, + "project_id": { + "type": "string" + }, + "refresh_token": { + "type": "string" + }, + "status": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_dto.BindingDTO": { + "type": "object", + "properties": { + "group_id": { + "type": "integer" + }, + "namespace": { + "type": "string" + }, + "public_model": { + "type": "string" + }, + "selector_type": { + "type": "string" + }, + "selector_value": { + "type": "string" + }, + "status": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_dto.ModelDTO": { + "type": "object", + "properties": { + "context_window": { + "type": "integer" + }, + "cost_per_token": { + "type": "number" + }, + "kind": { + "type": "string" + }, + "max_output_tokens": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "supports_fim": { + "type": "boolean" + }, + "supports_functions": { + "type": "boolean" + }, + "supports_tool_choice": { + "type": "boolean" + }, + "supports_vision": { + "type": "boolean" + } + } + }, + "github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO": { + "type": "object", + "properties": { + "base_url": { + "type": "string" + }, + "google_location": { + "type": "string" + }, + "google_project": { + "type": "string" + }, + "headers_profile": { + "type": "string" + }, + "models": { + "type": "array", + "items": { + "type": "string" + } + }, + "name": { + "type": "string" + }, + "static_headers": { + "type": "string" + }, + "status": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.APIKey": { + "type": "object", + "properties": { + "access_token": { + "type": "string" + }, + "account_id": { + "type": "string" + }, + "api_key": { + "type": "string" + }, + "auto_ban": { + "type": "boolean" + }, + "ban_reason": { + "type": "string" + }, + "ban_until": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "expires_at": { + "type": "string" + }, + "failure_rate": { + "type": "number" + }, + "failure_requests": { + "type": "integer" + }, + "group_id": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "project_id": { + "type": "string" + }, + "status": { + "type": "string" + }, + "success_rate": { + "type": "number" + }, + "success_requests": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + }, + "updatedAt": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_model.Binding": { + "type": "object", + "properties": { + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "group_id": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "namespace": { + "type": "string" + }, + "public_model": { + "type": "string" + }, + "selector_type": { + "type": "string" + }, + "selector_value": { + "type": "string" + }, + "status": { + "type": "string" + }, + "updatedAt": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_model.LogRecord": { + "type": "object", + "properties": { + "audit_reason": { + "type": "string" + }, + "client_ip": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "error_message": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "key_id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "master_id": { + "type": "integer" + }, + "model": { + "type": "string" + }, + "provider_id": { + "type": "integer" + }, + "provider_name": { + "type": "string" + }, + "provider_type": { + "type": "string" + }, + "request_body": { + "description": "optional, only when audit triggered", + "type": "string" + }, + "request_size": { + "type": "integer" + }, + "response_body": { + "description": "optional, only when audit triggered", + "type": "string" + }, + "response_size": { + "type": "integer" + }, + "status_code": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.Model": { + "type": "object", + "properties": { + "context_window": { + "type": "integer" + }, + "cost_per_token": { + "type": "number" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "id": { + "type": "integer" + }, + "kind": { + "type": "string" + }, + "max_output_tokens": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "supports_fim": { + "type": "boolean" + }, + "supports_functions": { + "type": "boolean" + }, + "supports_tool_choice": { + "type": "boolean" + }, + "supports_vision": { + "type": "boolean" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.Namespace": { + "type": "object", + "properties": { + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "description": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.ProviderGroup": { + "type": "object", + "properties": { + "base_url": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "failure_rate": { + "type": "number" + }, + "failure_requests": { + "type": "integer" + }, + "google_location": { + "type": "string" + }, + "google_project": { + "type": "string" + }, + "headers_profile": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "models": { + "description": "comma-separated list of supported models", + "type": "string" + }, + "name": { + "type": "string" + }, + "static_headers": { + "type": "string" + }, + "status": { + "type": "string" + }, + "success_rate": { + "type": "number" + }, + "success_requests": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + }, + "type": { + "description": "openai, anthropic, gemini", + "type": "string" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_service.LogWebhookConfig": { + "type": "object", + "properties": { + "cooldown_seconds": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "secret": { + "type": "string" + }, + "status_code_threshold": { + "type": "integer" + }, + "threshold": { + "type": "integer" + }, + "url": { + "type": "string" + }, + "window_seconds": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_service.ModelRegistryCheckResult": { + "type": "object", + "properties": { + "current_upstream_ref": { + "type": "string" + }, + "current_version": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "latest_version": { + "type": "string" + }, + "needs_refresh": { + "type": "boolean" + }, + "upstream_ref": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_service.ModelRegistryStatus": { + "type": "object", + "properties": { + "cache_current": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.modelRegistryFile" + }, + "cache_prev": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.modelRegistryFile" + }, + "enabled": { + "type": "boolean" + }, + "last_error": { + "type": "string" + }, + "last_refresh_at": { + "type": "integer" + }, + "models_dev_ref": { + "type": "string" + }, + "models_dev_url": { + "type": "string" + }, + "redis_meta": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "github_com_ez-api_ez-api_internal_service.modelRegistryFile": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/definitions/modelcap.Meta" + }, + "models": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/modelcap.Model" + } + } + } + }, + "gorm.DeletedAt": { + "type": "object", + "properties": { + "time": { + "type": "string" + }, + "valid": { + "description": "Valid is true if Time is not NULL", + "type": "boolean" + } + } + }, + "internal_api.APIKeyStatsSummaryResponse": { + "type": "object", + "properties": { + "failure_rate": { + "type": "number" + }, + "failure_requests": { + "type": "integer" + }, + "success_rate": { + "type": "number" + }, + "success_requests": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + } + } + }, + "internal_api.AboutResponse": { + "type": "object", + "properties": { + "description": { + "type": "string", + "example": "High-performance LLM API gateway" + }, + "name": { + "type": "string", + "example": "EZ-API Gateway" + }, + "repository": { + "type": "string", + "example": "https://github.com/ez-api/ez-api" + }, + "version": { + "type": "string", + "example": "0.1.0" + } + } + }, + "internal_api.AccessResponse": { + "type": "object", + "properties": { + "default_namespace": { + "type": "string" + }, + "namespaces": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "internal_api.AckAlertRequest": { + "type": "object", + "properties": { + "acked_by": { + "type": "string" + } + } + }, + "internal_api.AdminUsageStatsResponse": { + "type": "object", + "properties": { + "active_masters": { + "type": "integer" + }, + "by_master": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterUsageAgg" + } + }, + "by_provider": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.ProviderUsageAgg" + } + }, + "period": { + "type": "string" + }, + "total_masters": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + } + } + }, + "internal_api.AlertStats": { + "type": "object", + "properties": { + "acknowledged": { + "type": "integer" + }, + "active": { + "type": "integer" + }, + "critical": { + "type": "integer" + }, + "info": { + "type": "integer" + }, + "resolved": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "warning": { + "type": "integer" + } + } + }, + "internal_api.AlertThresholdView": { + "type": "object", + "properties": { + "global_qps": { + "type": "integer" + }, + "master_rpd": { + "type": "integer" + }, + "master_rpm": { + "type": "integer" + }, + "master_tpd": { + "type": "integer" + }, + "master_tpm": { + "type": "integer" + }, + "min_rpm_requests_1m": { + "type": "integer" + }, + "min_tpm_tokens_1m": { + "type": "integer" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.AlertView": { + "type": "object", + "properties": { + "acked_at": { + "type": "integer" + }, + "acked_by": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "expires_at": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "resolved_at": { + "type": "integer" + }, + "severity": { + "type": "string" + }, + "status": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.BatchActionRequest": { + "type": "object", + "properties": { + "action": { + "type": "string" + }, + "ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "status": { + "type": "string" + } + } + }, + "internal_api.BatchResponse": { + "type": "object", + "properties": { + "action": { + "type": "string" + }, + "failed": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.BatchResult" + } + }, + "success": { + "type": "array", + "items": { + "type": "integer" + } + } + } + }, + "internal_api.BatchResult": { + "type": "object", + "properties": { + "error": { + "type": "string" + }, + "id": { + "type": "integer" + } + } + }, + "internal_api.CountStats": { + "type": "object", + "properties": { + "active": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.CreateAlertRequest": { + "type": "object", + "required": [ + "severity", + "title", + "type" + ], + "properties": { + "expires_at": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "severity": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "internal_api.CreateMasterRequest": { + "type": "object", + "required": [ + "group", + "name" + ], + "properties": { + "global_qps": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "max_child_keys": { + "type": "integer" + }, + "name": { + "type": "string" + } + } + }, + "internal_api.DashboardSummaryResponse": { + "type": "object", + "properties": { + "keys": { + "$ref": "#/definitions/internal_api.CountStats" + }, + "latency": { + "$ref": "#/definitions/internal_api.LatencyStats" + }, + "masters": { + "$ref": "#/definitions/internal_api.CountStats" + }, + "period": { + "type": "string" + }, + "provider_keys": { + "$ref": "#/definitions/internal_api.ProviderKeyStats" + }, + "requests": { + "$ref": "#/definitions/internal_api.RequestStats" + }, + "tokens": { + "$ref": "#/definitions/internal_api.TokenStats" + }, + "top_models": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.TopModelStat" + } + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.DeleteLogsRequest": { + "type": "object", + "properties": { + "before": { + "type": "string" + }, + "key_id": { + "type": "integer" + }, + "model": { + "type": "string" + } + } + }, + "internal_api.DeleteLogsResponse": { + "type": "object", + "properties": { + "deleted_count": { + "type": "integer" + } + } + }, + "internal_api.GroupedStatsItem": { + "type": "object", + "properties": { + "avg_latency_ms": { + "type": "number" + }, + "count": { + "type": "integer" + }, + "date": { + "description": "For group_by=day", + "type": "string" + }, + "hour": { + "description": "For group_by=hour", + "type": "string" + }, + "minute": { + "description": "For group_by=minute", + "type": "string" + }, + "model": { + "description": "For group_by=model", + "type": "string" + }, + "month": { + "description": "For group_by=month", + "type": "string" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.GroupedStatsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.GroupedStatsItem" + } + } + } + }, + "internal_api.IssueChildKeyRequest": { + "type": "object", + "properties": { + "allow_ips": { + "type": "string" + }, + "deny_ips": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "group": { + "type": "string" + }, + "model_limits": { + "type": "string" + }, + "model_limits_enabled": { + "type": "boolean" + }, + "scopes": { + "type": "string" + } + } + }, + "internal_api.KeyUsageStat": { + "type": "object", + "properties": { + "key_id": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.LatencyStats": { + "type": "object", + "properties": { + "avg_ms": { + "type": "number" + } + } + }, + "internal_api.ListAlertsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.ListLogsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.LogView" + } + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.ListMasterLogsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterLogView" + } + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.LogStatsResponse": { + "type": "object", + "properties": { + "avg_latency_ms": { + "type": "number" + }, + "by_status": { + "type": "object", + "additionalProperties": { + "type": "integer", + "format": "int64" + } + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.LogView": { + "type": "object", + "properties": { + "audit_reason": { + "type": "string" + }, + "client_ip": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "error_message": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "key_id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "model": { + "type": "string" + }, + "provider_id": { + "type": "integer" + }, + "provider_name": { + "type": "string" + }, + "provider_type": { + "type": "string" + }, + "request_body": { + "type": "string" + }, + "request_size": { + "type": "integer" + }, + "response_size": { + "type": "integer" + }, + "status_code": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.ManageMasterRequest": { + "type": "object", + "required": [ + "action" + ], + "properties": { + "action": { + "description": "freeze/unfreeze", + "type": "string" + } + } + }, + "internal_api.MasterLogView": { + "type": "object", + "properties": { + "created_at": { + "type": "integer" + }, + "error_message": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "key_id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "model": { + "type": "string" + }, + "request_size": { + "type": "integer" + }, + "response_size": { + "type": "integer" + }, + "status_code": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.MasterRealtimeSummaryView": { + "type": "object", + "properties": { + "master_id": { + "type": "integer" + }, + "qps": { + "type": "integer" + }, + "rate_limited": { + "type": "boolean" + } + } + }, + "internal_api.MasterRealtimeView": { + "type": "object", + "properties": { + "qps": { + "type": "integer" + }, + "qps_limit": { + "type": "integer" + }, + "rate_limited": { + "type": "boolean" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.MasterUsageAgg": { + "type": "object", + "properties": { + "master_id": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.MasterUsageStatsResponse": { + "type": "object", + "properties": { + "by_key": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.KeyUsageStat" + } + }, + "by_model": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.ModelUsageStat" + } + }, + "period": { + "type": "string" + }, + "total_requests": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + } + } + }, + "internal_api.MasterView": { + "type": "object", + "properties": { + "created_at": { + "type": "integer" + }, + "default_namespace": { + "type": "string" + }, + "epoch": { + "type": "integer" + }, + "global_qps": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "max_child_keys": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "namespaces": { + "type": "string" + }, + "realtime": { + "$ref": "#/definitions/internal_api.MasterRealtimeView" + }, + "status": { + "type": "string" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.ModelUsageStat": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.NamespaceRequest": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "internal_api.OperationLogView": { + "type": "object", + "properties": { + "actor": { + "type": "string" + }, + "client_ip": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "error_message": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "method": { + "type": "string" + }, + "path": { + "type": "string" + }, + "query": { + "type": "string" + }, + "request_id": { + "type": "string" + }, + "status_code": { + "type": "integer" + }, + "user_agent": { + "type": "string" + } + } + }, + "internal_api.ProviderKeyStats": { + "type": "object", + "properties": { + "active": { + "type": "integer" + }, + "auto_disabled": { + "type": "integer" + }, + "suspended": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.ProviderUsageAgg": { + "type": "object", + "properties": { + "provider_id": { + "type": "integer" + }, + "provider_name": { + "type": "string" + }, + "provider_type": { + "type": "string" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.RequestStats": { + "type": "object", + "properties": { + "error_rate": { + "type": "number" + }, + "failed": { + "type": "integer" + }, + "success": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.StatusResponse": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "ok" + }, + "uptime": { + "type": "string", + "example": "72h30m15s" + }, + "version": { + "type": "string", + "example": "0.1.0" + } + } + }, + "internal_api.SystemRealtimeView": { + "type": "object", + "properties": { + "by_master": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterRealtimeSummaryView" + } + }, + "qps": { + "type": "integer" + }, + "rate_limited_count": { + "type": "integer" + }, + "rpm": { + "type": "integer" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.TokenStats": { + "type": "object", + "properties": { + "input": { + "type": "integer" + }, + "output": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.TokenView": { + "type": "object", + "properties": { + "allow_ips": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "default_namespace": { + "type": "string" + }, + "deny_ips": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "issued_at_epoch": { + "type": "integer" + }, + "issued_by": { + "type": "string" + }, + "last_accessed_at": { + "type": "string" + }, + "model_limits": { + "type": "string" + }, + "model_limits_enabled": { + "type": "boolean" + }, + "namespaces": { + "type": "string" + }, + "quota_limit": { + "type": "integer" + }, + "quota_reset_at": { + "type": "string" + }, + "quota_reset_type": { + "type": "string" + }, + "quota_used": { + "type": "integer" + }, + "request_count": { + "type": "integer" + }, + "scopes": { + "type": "string" + }, + "status": { + "type": "string" + }, + "updated_at": { + "type": "integer" + }, + "used_tokens": { + "type": "integer" + } + } + }, + "internal_api.TopModelStat": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.UpdateAccessRequest": { + "type": "object", + "properties": { + "default_namespace": { + "type": "string" + }, + "namespaces": { + "type": "array", + "items": { + "type": "string" + } + }, + "propagate_to_keys": { + "type": "boolean" + } + } + }, + "internal_api.UpdateAlertThresholdsRequest": { + "type": "object", + "properties": { + "global_qps": { + "type": "integer" + }, + "master_rpd": { + "type": "integer" + }, + "master_rpm": { + "type": "integer" + }, + "master_tpd": { + "type": "integer" + }, + "master_tpm": { + "type": "integer" + }, + "min_rpm_requests_1m": { + "type": "integer" + }, + "min_tpm_tokens_1m": { + "type": "integer" + } + } + }, + "internal_api.UpdateMasterRequest": { + "type": "object", + "properties": { + "global_qps": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "max_child_keys": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "propagate_to_keys": { + "type": "boolean" + } + } + }, + "internal_api.UpdateNamespaceRequest": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "internal_api.UpdateTokenRequest": { + "type": "object", + "properties": { + "allow_ips": { + "type": "string" + }, + "deny_ips": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "model_limits": { + "type": "string" + }, + "model_limits_enabled": { + "type": "boolean" + }, + "scopes": { + "type": "string" + }, + "status": { + "description": "active/suspended", + "type": "string" + } + } + }, + "internal_api.WhoamiResponse": { + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "example": 1703505600 + }, + "default_namespace": { + "type": "string", + "example": "default" + }, + "epoch": { + "type": "integer", + "example": 1 + }, + "global_qps": { + "type": "integer", + "example": 100 + }, + "group": { + "type": "string", + "example": "default" + }, + "id": { + "description": "Master fields (only present when type is \"master\")", + "type": "integer", + "example": 1 + }, + "issued_at_epoch": { + "type": "integer", + "example": 1 + }, + "issued_by": { + "type": "string", + "example": "master" + }, + "master_id": { + "description": "Key fields (only present when type is \"key\")", + "type": "integer", + "example": 1 + }, + "max_child_keys": { + "type": "integer", + "example": 5 + }, + "name": { + "type": "string", + "example": "tenant-a" + }, + "namespaces": { + "type": "string", + "example": "default,ns1" + }, + "role": { + "description": "Admin fields (only present when type is \"admin\")", + "type": "string", + "example": "admin" + }, + "scopes": { + "type": "string", + "example": "chat:write" + }, + "status": { + "type": "string", + "example": "active" + }, + "type": { + "description": "Type of the authenticated identity: \"admin\", \"master\", or \"key\"", + "type": "string", + "example": "master" + }, + "updated_at": { + "type": "integer", + "example": 1703505600 + } + } + }, + "internal_api.apiKeyStatsFlushEntry": { + "type": "object", + "properties": { + "api_key_id": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "success_requests": { + "type": "integer" + } + } + }, + "internal_api.apiKeyStatsFlushRequest": { + "type": "object", + "properties": { + "keys": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.apiKeyStatsFlushEntry" + } + } + } + }, + "internal_api.refreshModelRegistryRequest": { + "type": "object", + "properties": { + "ref": { + "type": "string" + } + } + }, + "internal_api.reportAlertEntry": { + "type": "object", + "required": [ + "severity", + "title", + "type" + ], + "properties": { + "fingerprint": { + "type": "string" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "severity": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "internal_api.reportAlertsRequest": { + "type": "object", + "required": [ + "alerts" + ], + "properties": { + "alerts": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.reportAlertEntry" + } + } + } + }, + "internal_api.reportAlertsResponse": { + "type": "object", + "properties": { + "accepted": { + "type": "integer" + }, + "deduplicated": { + "type": "integer" + }, + "errors": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "internal_api.statsFlushEntry": { + "type": "object", + "properties": { + "last_accessed_at": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "token_hash": { + "type": "string" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.statsFlushRequest": { + "type": "object", + "properties": { + "keys": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.statsFlushEntry" + } + } + } + }, + "modelcap.Meta": { + "type": "object", + "properties": { + "checksum": { + "type": "string" + }, + "source": { + "type": "string" + }, + "updated_at": { + "type": "string" + }, + "upstream_ref": { + "type": "string" + }, + "upstream_url": { + "type": "string" + }, + "version": { + "type": "string" + } + } + }, + "modelcap.Model": { + "type": "object", + "properties": { + "context_window": { + "type": "integer" + }, + "cost_per_token": { + "type": "number" + }, + "kind": { + "type": "string" + }, + "max_output_tokens": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "supports_fim": { + "type": "boolean" + }, + "supports_functions": { + "type": "boolean" + }, + "supports_stream": { + "type": "boolean" + }, + "supports_tool_choice": { + "type": "boolean" + }, + "supports_vision": { + "type": "boolean" + } + } + } + }, + "securityDefinitions": { + "AdminAuth": { + "description": "Type \"Bearer\" followed by a space and the admin token. Example: Bearer admin123", + "type": "apiKey", + "name": "Authorization", + "in": "header" + }, + "MasterAuth": { + "description": "Type \"Bearer\" followed by a space and the master key. Example: Bearer sk-xxx", + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } +}` + +// SwaggerInfo holds exported Swagger Info so clients can modify it +var SwaggerInfo = &swag.Spec{ + Version: "0.0.1", + Host: "localhost:8080", + BasePath: "/", + Schemes: []string{}, + Title: "EZ-API Control Plane", + Description: "Management API for EZ-API Gateway system.", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate, + LeftDelim: "{{", + RightDelim: "}}", +} + +func init() { + swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) +} diff --git a/docs/swagger/swagger.json b/docs/swagger/swagger.json new file mode 100644 index 0000000..59a8ba6 --- /dev/null +++ b/docs/swagger/swagger.json @@ -0,0 +1,6220 @@ +{ + "swagger": "2.0", + "info": { + "description": "Management API for EZ-API Gateway system.", + "title": "EZ-API Control Plane", + "termsOfService": "http://swagger.io/terms/", + "contact": { + "name": "API Support", + "url": "http://www.swagger.io/support", + "email": "support@swagger.io" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "0.0.1" + }, + "host": "localhost:8080", + "basePath": "/", + "paths": { + "/about": { + "get": { + "description": "Returns system metadata for display on an about page", + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "Get system information", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AboutResponse" + } + } + } + } + }, + "/admin/alerts": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List system alerts with optional filters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List alerts", + "parameters": [ + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "offset", + "name": "offset", + "in": "query" + }, + { + "type": "string", + "description": "filter by status (active, acknowledged, resolved, dismissed)", + "name": "status", + "in": "query" + }, + { + "type": "string", + "description": "filter by severity (info, warning, critical)", + "name": "severity", + "in": "query" + }, + { + "type": "string", + "description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down, traffic_spike)", + "name": "type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.ListAlertsResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a new system alert", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create alert", + "parameters": [ + { + "description": "Alert data", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.CreateAlertRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/stats": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get alert count statistics by status and severity", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Alert statistics", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertStats" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/thresholds": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get current alert threshold configuration for traffic spike detection", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get alert thresholds", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertThresholdView" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update alert threshold configuration for traffic spike detection", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update alert thresholds", + "parameters": [ + { + "description": "Threshold configuration", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateAlertThresholdsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertThresholdView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a single alert by ID", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Dismiss an alert (soft delete)", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Dismiss alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/{id}/ack": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Mark an alert as acknowledged", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Acknowledge alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Ack data", + "name": "request", + "in": "body", + "schema": { + "$ref": "#/definitions/internal_api.AckAlertRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/alerts/{id}/resolve": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Mark an alert as resolved", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Resolve alert", + "parameters": [ + { + "type": "integer", + "description": "Alert ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/api-keys": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List API keys with optional filters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List API keys", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "filter by group_id", + "name": "group_id", + "in": "query" + }, + { + "type": "string", + "description": "filter by status (active, suspended, auto_disabled, manual_disabled)", + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create an API key for a provider group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create an API key", + "parameters": [ + { + "description": "API key payload", + "name": "key", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/api-keys/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete or status update for api keys", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch api keys", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/api-keys/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get an API key by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get API key", + "parameters": [ + { + "type": "integer", + "description": "APIKey ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update an API key", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update API key", + "parameters": [ + { + "type": "integer", + "description": "APIKey ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "API key payload", + "name": "key", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.APIKey" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete an API key", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete API key", + "parameters": [ + { + "type": "integer", + "description": "APIKey ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/apikey-stats/summary": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Aggregate APIKey success/failure stats across all provider groups", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "APIKey stats summary (admin)", + "parameters": [ + { + "type": "integer", + "description": "Start time (unix seconds)", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "End time (unix seconds)", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.APIKeyStatsSummaryResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/bindings": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all configured bindings", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List bindings", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by namespace/public_model", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a new (namespace, public_model) binding to a provider group and selector", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create a new binding", + "parameters": [ + { + "description": "Binding Info", + "name": "binding", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.BindingDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/bindings/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete or status update for bindings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch bindings", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/bindings/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a binding by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get a binding", + "parameters": [ + { + "type": "integer", + "description": "Binding ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update an existing binding", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update a binding", + "parameters": [ + { + "type": "integer", + "description": "Binding ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Binding Info", + "name": "binding", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.BindingDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Binding" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a binding by id and rebuild bindings snapshot", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete a binding", + "parameters": [ + { + "type": "integer", + "description": "Binding ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/dashboard/summary": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns aggregated metrics for dashboard display including requests, tokens, latency, masters, keys, and provider keys statistics", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Dashboard summary", + "parameters": [ + { + "type": "string", + "description": "time period: today, week, month, all", + "name": "period", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.DashboardSummaryResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/features": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns all feature flags stored in Redis (meta:features)", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List feature flags", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates selected feature flags (meta:features). Values are stored as strings.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update feature flags", + "parameters": [ + { + "description": "Feature map", + "name": "request", + "in": "body", + "required": true, + "schema": { + "type": "object" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/keys/{id}/access": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns key default_namespace and namespaces", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get key access settings", + "parameters": [ + { + "type": "integer", + "description": "Key ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates key default_namespace and namespaces and syncs to Redis", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update key access settings", + "parameters": [ + { + "type": "integer", + "description": "Key ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Access settings", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateAccessRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/logs": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List request logs with basic filtering/pagination. Returns full log records including request_body.", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List logs (admin)", + "parameters": [ + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "offset", + "name": "offset", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + }, + { + "type": "integer", + "description": "key id", + "name": "key_id", + "in": "query" + }, + { + "type": "string", + "description": "route group", + "name": "group", + "in": "query" + }, + { + "type": "string", + "description": "model", + "name": "model", + "in": "query" + }, + { + "type": "integer", + "description": "status code", + "name": "status_code", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.ListLogsResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete logs before a given timestamp with optional filters", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete logs (admin)", + "parameters": [ + { + "description": "Delete filters", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.DeleteLogsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.DeleteLogsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/logs/stats": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Aggregate log stats with basic filtering. Use group_by param for grouped statistics (model/day/month/hour/minute). Without group_by returns LogStatsResponse; with group_by returns GroupedStatsResponse. Note: minute-level aggregation is limited to 6-hour time ranges.", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Log stats (admin)", + "parameters": [ + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + }, + { + "enum": [ + "model", + "day", + "month", + "hour", + "minute" + ], + "type": "string", + "description": "group by dimension: model, day, month, hour, minute. Returns GroupedStatsResponse when specified.", + "name": "group_by", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Grouped stats (when group_by is specified)", + "schema": { + "$ref": "#/definitions/internal_api.GroupedStatsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/logs/webhook": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns current webhook notification config", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get log webhook config", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates webhook notification config", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update log webhook config", + "parameters": [ + { + "description": "Webhook config", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all master tenants", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List masters", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/group", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterView" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a new master account (tenant)", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create a new master tenant", + "parameters": [ + { + "description": "Master Info", + "name": "master", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.CreateMasterRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete or status update for masters", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch masters", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a master tenant by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update master fields; optionally propagate group to existing keys", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateMasterRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Suspends a master and revokes all existing keys by bumping epoch and syncing to Redis", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete (revoke) master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/access": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns master default_namespace and namespaces", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get master access settings", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Updates master default_namespace and namespaces; optionally propagate to existing keys", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update master access settings", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Access settings", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateAccessRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AccessResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/keys": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Issue a new access token (child key) for a specified master. The key still belongs to the master; issuer is recorded as admin for audit.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Issue a child key on behalf of a master", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Key Request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.IssueChildKeyRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/manage": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Freeze or unfreeze a master tenant", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Manage master status", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Action", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.ManageMasterRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/masters/{id}/realtime": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Return realtime counters for the specified master", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Master realtime stats (admin)", + "parameters": [ + { + "type": "integer", + "description": "Master ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterRealtimeView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/check": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Checks models.dev commit SHA for a ref and indicates whether refresh is needed (does not apply changes)", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Check model registry upstream version", + "parameters": [ + { + "description": "optional override ref", + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/internal_api.refreshModelRegistryRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.ModelRegistryCheckResult" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/refresh": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Fetches models.dev, computes per-binding capabilities, and updates Redis meta:models", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Refresh model registry from models.dev", + "parameters": [ + { + "description": "optional override ref", + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/internal_api.refreshModelRegistryRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/rollback": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Rollback meta:models to previous cached last-good version", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Rollback model registry", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/model-registry/status": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Returns Redis meta and local last-good cache info for model capability registry", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get model registry status", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.ModelRegistryStatus" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/models": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a list of all registered models", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List all models", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/kind", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Model" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Register a supported model with its capabilities", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Register a new model", + "parameters": [ + { + "description": "Model Info", + "name": "model", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ModelDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Model" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/models/batch": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Batch delete for models", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Batch models", + "parameters": [ + { + "description": "Batch payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.BatchActionRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.BatchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/models/{id}": { + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update an existing model's configuration", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update a model", + "parameters": [ + { + "type": "integer", + "description": "Model ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Model Info", + "name": "model", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ModelDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Model" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a model by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete a model", + "parameters": [ + { + "type": "integer", + "description": "Model ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/namespaces": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all namespaces", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List namespaces", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/description", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a namespace for bindings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create namespace", + "parameters": [ + { + "description": "Namespace payload", + "name": "namespace", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.NamespaceRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/namespaces/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a namespace by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get namespace", + "parameters": [ + { + "type": "integer", + "description": "Namespace ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update a namespace", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update namespace", + "parameters": [ + { + "type": "integer", + "description": "Namespace ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update payload", + "name": "namespace", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateNamespaceRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.Namespace" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a namespace and its bindings", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete namespace", + "parameters": [ + { + "type": "integer", + "description": "Namespace ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/operation-logs": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List admin operation logs", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List operation logs", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by actor/method/path", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.OperationLogView" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/provider-groups": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "List all provider groups", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "List provider groups", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by name/type", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Create a provider group definition", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Create a provider group", + "parameters": [ + { + "description": "Provider group payload", + "name": "group", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/provider-groups/{id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get a provider group by id", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Get provider group", + "parameters": [ + { + "type": "integer", + "description": "ProviderGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Update a provider group", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Update provider group", + "parameters": [ + { + "type": "integer", + "description": "ProviderGroup ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Provider group payload", + "name": "group", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Delete a provider group and its api keys/bindings", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Delete provider group", + "parameters": [ + { + "type": "integer", + "description": "ProviderGroup ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/realtime": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Return aggregated realtime counters across all masters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "System-level realtime stats (admin)", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.SystemRealtimeView" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/stats": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Aggregate request stats across all masters", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Usage stats (admin)", + "parameters": [ + { + "type": "string", + "description": "today|week|month|all", + "name": "period", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.AdminUsageStatsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/admin/sync/snapshot": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Force full synchronization of DB state to Redis", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Force sync snapshot", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/auth/whoami": { + "get": { + "security": [ + { + "AdminAuth": [] + }, + { + "MasterAuth": [] + } + ], + "description": "Returns the identity of the authenticated user based on the Authorization header.\nSupports Admin Token, Master Key, and Child Key (API Key) authentication.\n\nResponse varies by token type:\n- Admin Token: {\"type\": \"admin\", \"role\": \"admin\"}\n- Master Key: {\"type\": \"master\", \"id\": 1, \"name\": \"...\", ...}\n- Child Key: {\"type\": \"key\", \"id\": 5, \"master_id\": 1, \"issued_by\": \"master\", ...}", + "produces": [ + "application/json" + ], + "tags": [ + "auth" + ], + "summary": "Get current identity", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.WhoamiResponse" + } + }, + "401": { + "description": "Invalid or missing token", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/internal/alerts/report": { + "post": { + "description": "Internal endpoint for Data Plane to report alerts to Control Plane", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Report alerts from DP", + "parameters": [ + { + "description": "Alerts to report", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/internal/apikey-stats/flush": { + "post": { + "description": "Internal endpoint for flushing accumulated APIKey stats from DP to CP database", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Flush API key stats", + "parameters": [ + { + "description": "Stats to flush", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.apiKeyStatsFlushRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/internal/stats/flush": { + "post": { + "description": "Internal endpoint for flushing accumulated key usage stats from DP to CP database", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Flush key stats", + "parameters": [ + { + "description": "Stats to flush", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.statsFlushRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/logs": { + "post": { + "description": "Internal endpoint for ingesting logs from Balancer", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "system" + ], + "summary": "Ingest logs", + "parameters": [ + { + "description": "Log Record", + "name": "log", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_model.LogRecord" + } + } + ], + "responses": { + "202": { + "description": "Accepted", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/status": { + "get": { + "description": "Returns public runtime status information without sensitive data", + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "Get system status", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.StatusResponse" + } + } + } + } + }, + "/v1/logs": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "List request logs for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "List logs (master)", + "parameters": [ + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "description": "offset", + "name": "offset", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + }, + { + "type": "string", + "description": "model", + "name": "model", + "in": "query" + }, + { + "type": "integer", + "description": "status code", + "name": "status_code", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.ListMasterLogsResponse" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/logs/stats": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Aggregate request log stats for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Log stats (master)", + "parameters": [ + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.LogStatsResponse" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/realtime": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Return realtime counters for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Master realtime stats", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterRealtimeView" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/self": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Returns master metadata for the authenticated master key", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Get current master info", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterView" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/stats": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Aggregate request stats for the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Usage stats (master)", + "parameters": [ + { + "type": "string", + "description": "today|week|month|all", + "name": "period", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "unix seconds", + "name": "until", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.MasterUsageStatsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/tokens": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "List child keys issued under the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "List child keys", + "parameters": [ + { + "type": "integer", + "description": "page (1-based)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "limit (default 50, max 200)", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "search by group/scopes/namespaces/status", + "name": "search", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.TokenView" + } + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "post": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Issue a new access token (child key) for the authenticated master", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Issue a child key", + "parameters": [ + { + "description": "Key Request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.IssueChildKeyRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, + "/v1/tokens/{id}": { + "get": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Get a child key by id under the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Get child key", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.TokenView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "put": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Update token scopes/status under the authenticated master", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Update child key", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update payload", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.UpdateTokenRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.TokenView" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + }, + "delete": { + "security": [ + { + "MasterAuth": [] + } + ], + "description": "Suspends a child key under the authenticated master", + "produces": [ + "application/json" + ], + "tags": [ + "master" + ], + "summary": "Delete (revoke) child key", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + } + }, + "definitions": { + "gin.H": { + "type": "object", + "additionalProperties": {} + }, + "github_com_ez-api_ez-api_internal_dto.APIKeyDTO": { + "type": "object", + "properties": { + "access_token": { + "type": "string" + }, + "account_id": { + "type": "string" + }, + "api_key": { + "type": "string" + }, + "auto_ban": { + "type": "boolean" + }, + "ban_reason": { + "type": "string" + }, + "ban_until": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "group_id": { + "type": "integer" + }, + "project_id": { + "type": "string" + }, + "refresh_token": { + "type": "string" + }, + "status": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_dto.BindingDTO": { + "type": "object", + "properties": { + "group_id": { + "type": "integer" + }, + "namespace": { + "type": "string" + }, + "public_model": { + "type": "string" + }, + "selector_type": { + "type": "string" + }, + "selector_value": { + "type": "string" + }, + "status": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_dto.ModelDTO": { + "type": "object", + "properties": { + "context_window": { + "type": "integer" + }, + "cost_per_token": { + "type": "number" + }, + "kind": { + "type": "string" + }, + "max_output_tokens": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "supports_fim": { + "type": "boolean" + }, + "supports_functions": { + "type": "boolean" + }, + "supports_tool_choice": { + "type": "boolean" + }, + "supports_vision": { + "type": "boolean" + } + } + }, + "github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO": { + "type": "object", + "properties": { + "base_url": { + "type": "string" + }, + "google_location": { + "type": "string" + }, + "google_project": { + "type": "string" + }, + "headers_profile": { + "type": "string" + }, + "models": { + "type": "array", + "items": { + "type": "string" + } + }, + "name": { + "type": "string" + }, + "static_headers": { + "type": "string" + }, + "status": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.APIKey": { + "type": "object", + "properties": { + "access_token": { + "type": "string" + }, + "account_id": { + "type": "string" + }, + "api_key": { + "type": "string" + }, + "auto_ban": { + "type": "boolean" + }, + "ban_reason": { + "type": "string" + }, + "ban_until": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "expires_at": { + "type": "string" + }, + "failure_rate": { + "type": "number" + }, + "failure_requests": { + "type": "integer" + }, + "group_id": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "project_id": { + "type": "string" + }, + "status": { + "type": "string" + }, + "success_rate": { + "type": "number" + }, + "success_requests": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + }, + "updatedAt": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_model.Binding": { + "type": "object", + "properties": { + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "group_id": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "namespace": { + "type": "string" + }, + "public_model": { + "type": "string" + }, + "selector_type": { + "type": "string" + }, + "selector_value": { + "type": "string" + }, + "status": { + "type": "string" + }, + "updatedAt": { + "type": "string" + }, + "weight": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_model.LogRecord": { + "type": "object", + "properties": { + "audit_reason": { + "type": "string" + }, + "client_ip": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "error_message": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "key_id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "master_id": { + "type": "integer" + }, + "model": { + "type": "string" + }, + "provider_id": { + "type": "integer" + }, + "provider_name": { + "type": "string" + }, + "provider_type": { + "type": "string" + }, + "request_body": { + "description": "optional, only when audit triggered", + "type": "string" + }, + "request_size": { + "type": "integer" + }, + "response_body": { + "description": "optional, only when audit triggered", + "type": "string" + }, + "response_size": { + "type": "integer" + }, + "status_code": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.Model": { + "type": "object", + "properties": { + "context_window": { + "type": "integer" + }, + "cost_per_token": { + "type": "number" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "id": { + "type": "integer" + }, + "kind": { + "type": "string" + }, + "max_output_tokens": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "supports_fim": { + "type": "boolean" + }, + "supports_functions": { + "type": "boolean" + }, + "supports_tool_choice": { + "type": "boolean" + }, + "supports_vision": { + "type": "boolean" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.Namespace": { + "type": "object", + "properties": { + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "description": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_model.ProviderGroup": { + "type": "object", + "properties": { + "base_url": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "deletedAt": { + "$ref": "#/definitions/gorm.DeletedAt" + }, + "failure_rate": { + "type": "number" + }, + "failure_requests": { + "type": "integer" + }, + "google_location": { + "type": "string" + }, + "google_project": { + "type": "string" + }, + "headers_profile": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "models": { + "description": "comma-separated list of supported models", + "type": "string" + }, + "name": { + "type": "string" + }, + "static_headers": { + "type": "string" + }, + "status": { + "type": "string" + }, + "success_rate": { + "type": "number" + }, + "success_requests": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + }, + "type": { + "description": "openai, anthropic, gemini", + "type": "string" + }, + "updatedAt": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_service.LogWebhookConfig": { + "type": "object", + "properties": { + "cooldown_seconds": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "secret": { + "type": "string" + }, + "status_code_threshold": { + "type": "integer" + }, + "threshold": { + "type": "integer" + }, + "url": { + "type": "string" + }, + "window_seconds": { + "type": "integer" + } + } + }, + "github_com_ez-api_ez-api_internal_service.ModelRegistryCheckResult": { + "type": "object", + "properties": { + "current_upstream_ref": { + "type": "string" + }, + "current_version": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "latest_version": { + "type": "string" + }, + "needs_refresh": { + "type": "boolean" + }, + "upstream_ref": { + "type": "string" + } + } + }, + "github_com_ez-api_ez-api_internal_service.ModelRegistryStatus": { + "type": "object", + "properties": { + "cache_current": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.modelRegistryFile" + }, + "cache_prev": { + "$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.modelRegistryFile" + }, + "enabled": { + "type": "boolean" + }, + "last_error": { + "type": "string" + }, + "last_refresh_at": { + "type": "integer" + }, + "models_dev_ref": { + "type": "string" + }, + "models_dev_url": { + "type": "string" + }, + "redis_meta": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "github_com_ez-api_ez-api_internal_service.modelRegistryFile": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/definitions/modelcap.Meta" + }, + "models": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/modelcap.Model" + } + } + } + }, + "gorm.DeletedAt": { + "type": "object", + "properties": { + "time": { + "type": "string" + }, + "valid": { + "description": "Valid is true if Time is not NULL", + "type": "boolean" + } + } + }, + "internal_api.APIKeyStatsSummaryResponse": { + "type": "object", + "properties": { + "failure_rate": { + "type": "number" + }, + "failure_requests": { + "type": "integer" + }, + "success_rate": { + "type": "number" + }, + "success_requests": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + } + } + }, + "internal_api.AboutResponse": { + "type": "object", + "properties": { + "description": { + "type": "string", + "example": "High-performance LLM API gateway" + }, + "name": { + "type": "string", + "example": "EZ-API Gateway" + }, + "repository": { + "type": "string", + "example": "https://github.com/ez-api/ez-api" + }, + "version": { + "type": "string", + "example": "0.1.0" + } + } + }, + "internal_api.AccessResponse": { + "type": "object", + "properties": { + "default_namespace": { + "type": "string" + }, + "namespaces": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "internal_api.AckAlertRequest": { + "type": "object", + "properties": { + "acked_by": { + "type": "string" + } + } + }, + "internal_api.AdminUsageStatsResponse": { + "type": "object", + "properties": { + "active_masters": { + "type": "integer" + }, + "by_master": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterUsageAgg" + } + }, + "by_provider": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.ProviderUsageAgg" + } + }, + "period": { + "type": "string" + }, + "total_masters": { + "type": "integer" + }, + "total_requests": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + } + } + }, + "internal_api.AlertStats": { + "type": "object", + "properties": { + "acknowledged": { + "type": "integer" + }, + "active": { + "type": "integer" + }, + "critical": { + "type": "integer" + }, + "info": { + "type": "integer" + }, + "resolved": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "warning": { + "type": "integer" + } + } + }, + "internal_api.AlertThresholdView": { + "type": "object", + "properties": { + "global_qps": { + "type": "integer" + }, + "master_rpd": { + "type": "integer" + }, + "master_rpm": { + "type": "integer" + }, + "master_tpd": { + "type": "integer" + }, + "master_tpm": { + "type": "integer" + }, + "min_rpm_requests_1m": { + "type": "integer" + }, + "min_tpm_tokens_1m": { + "type": "integer" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.AlertView": { + "type": "object", + "properties": { + "acked_at": { + "type": "integer" + }, + "acked_by": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "expires_at": { + "type": "integer" + }, + "id": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "resolved_at": { + "type": "integer" + }, + "severity": { + "type": "string" + }, + "status": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.BatchActionRequest": { + "type": "object", + "properties": { + "action": { + "type": "string" + }, + "ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "status": { + "type": "string" + } + } + }, + "internal_api.BatchResponse": { + "type": "object", + "properties": { + "action": { + "type": "string" + }, + "failed": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.BatchResult" + } + }, + "success": { + "type": "array", + "items": { + "type": "integer" + } + } + } + }, + "internal_api.BatchResult": { + "type": "object", + "properties": { + "error": { + "type": "string" + }, + "id": { + "type": "integer" + } + } + }, + "internal_api.CountStats": { + "type": "object", + "properties": { + "active": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.CreateAlertRequest": { + "type": "object", + "required": [ + "severity", + "title", + "type" + ], + "properties": { + "expires_at": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "severity": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "internal_api.CreateMasterRequest": { + "type": "object", + "required": [ + "group", + "name" + ], + "properties": { + "global_qps": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "max_child_keys": { + "type": "integer" + }, + "name": { + "type": "string" + } + } + }, + "internal_api.DashboardSummaryResponse": { + "type": "object", + "properties": { + "keys": { + "$ref": "#/definitions/internal_api.CountStats" + }, + "latency": { + "$ref": "#/definitions/internal_api.LatencyStats" + }, + "masters": { + "$ref": "#/definitions/internal_api.CountStats" + }, + "period": { + "type": "string" + }, + "provider_keys": { + "$ref": "#/definitions/internal_api.ProviderKeyStats" + }, + "requests": { + "$ref": "#/definitions/internal_api.RequestStats" + }, + "tokens": { + "$ref": "#/definitions/internal_api.TokenStats" + }, + "top_models": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.TopModelStat" + } + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.DeleteLogsRequest": { + "type": "object", + "properties": { + "before": { + "type": "string" + }, + "key_id": { + "type": "integer" + }, + "model": { + "type": "string" + } + } + }, + "internal_api.DeleteLogsResponse": { + "type": "object", + "properties": { + "deleted_count": { + "type": "integer" + } + } + }, + "internal_api.GroupedStatsItem": { + "type": "object", + "properties": { + "avg_latency_ms": { + "type": "number" + }, + "count": { + "type": "integer" + }, + "date": { + "description": "For group_by=day", + "type": "string" + }, + "hour": { + "description": "For group_by=hour", + "type": "string" + }, + "minute": { + "description": "For group_by=minute", + "type": "string" + }, + "model": { + "description": "For group_by=model", + "type": "string" + }, + "month": { + "description": "For group_by=month", + "type": "string" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.GroupedStatsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.GroupedStatsItem" + } + } + } + }, + "internal_api.IssueChildKeyRequest": { + "type": "object", + "properties": { + "allow_ips": { + "type": "string" + }, + "deny_ips": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "group": { + "type": "string" + }, + "model_limits": { + "type": "string" + }, + "model_limits_enabled": { + "type": "boolean" + }, + "scopes": { + "type": "string" + } + } + }, + "internal_api.KeyUsageStat": { + "type": "object", + "properties": { + "key_id": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.LatencyStats": { + "type": "object", + "properties": { + "avg_ms": { + "type": "number" + } + } + }, + "internal_api.ListAlertsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.AlertView" + } + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.ListLogsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.LogView" + } + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.ListMasterLogsResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterLogView" + } + }, + "limit": { + "type": "integer" + }, + "offset": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.LogStatsResponse": { + "type": "object", + "properties": { + "avg_latency_ms": { + "type": "number" + }, + "by_status": { + "type": "object", + "additionalProperties": { + "type": "integer", + "format": "int64" + } + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.LogView": { + "type": "object", + "properties": { + "audit_reason": { + "type": "string" + }, + "client_ip": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "error_message": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "key_id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "model": { + "type": "string" + }, + "provider_id": { + "type": "integer" + }, + "provider_name": { + "type": "string" + }, + "provider_type": { + "type": "string" + }, + "request_body": { + "type": "string" + }, + "request_size": { + "type": "integer" + }, + "response_size": { + "type": "integer" + }, + "status_code": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.ManageMasterRequest": { + "type": "object", + "required": [ + "action" + ], + "properties": { + "action": { + "description": "freeze/unfreeze", + "type": "string" + } + } + }, + "internal_api.MasterLogView": { + "type": "object", + "properties": { + "created_at": { + "type": "integer" + }, + "error_message": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "key_id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "model": { + "type": "string" + }, + "request_size": { + "type": "integer" + }, + "response_size": { + "type": "integer" + }, + "status_code": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.MasterRealtimeSummaryView": { + "type": "object", + "properties": { + "master_id": { + "type": "integer" + }, + "qps": { + "type": "integer" + }, + "rate_limited": { + "type": "boolean" + } + } + }, + "internal_api.MasterRealtimeView": { + "type": "object", + "properties": { + "qps": { + "type": "integer" + }, + "qps_limit": { + "type": "integer" + }, + "rate_limited": { + "type": "boolean" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.MasterUsageAgg": { + "type": "object", + "properties": { + "master_id": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.MasterUsageStatsResponse": { + "type": "object", + "properties": { + "by_key": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.KeyUsageStat" + } + }, + "by_model": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.ModelUsageStat" + } + }, + "period": { + "type": "string" + }, + "total_requests": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + } + } + }, + "internal_api.MasterView": { + "type": "object", + "properties": { + "created_at": { + "type": "integer" + }, + "default_namespace": { + "type": "string" + }, + "epoch": { + "type": "integer" + }, + "global_qps": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "max_child_keys": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "namespaces": { + "type": "string" + }, + "realtime": { + "$ref": "#/definitions/internal_api.MasterRealtimeView" + }, + "status": { + "type": "string" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.ModelUsageStat": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.NamespaceRequest": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "internal_api.OperationLogView": { + "type": "object", + "properties": { + "actor": { + "type": "string" + }, + "client_ip": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "error_message": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "latency_ms": { + "type": "integer" + }, + "method": { + "type": "string" + }, + "path": { + "type": "string" + }, + "query": { + "type": "string" + }, + "request_id": { + "type": "string" + }, + "status_code": { + "type": "integer" + }, + "user_agent": { + "type": "string" + } + } + }, + "internal_api.ProviderKeyStats": { + "type": "object", + "properties": { + "active": { + "type": "integer" + }, + "auto_disabled": { + "type": "integer" + }, + "suspended": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.ProviderUsageAgg": { + "type": "object", + "properties": { + "provider_id": { + "type": "integer" + }, + "provider_name": { + "type": "string" + }, + "provider_type": { + "type": "string" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.RequestStats": { + "type": "object", + "properties": { + "error_rate": { + "type": "number" + }, + "failed": { + "type": "integer" + }, + "success": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.StatusResponse": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "ok" + }, + "uptime": { + "type": "string", + "example": "72h30m15s" + }, + "version": { + "type": "string", + "example": "0.1.0" + } + } + }, + "internal_api.SystemRealtimeView": { + "type": "object", + "properties": { + "by_master": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.MasterRealtimeSummaryView" + } + }, + "qps": { + "type": "integer" + }, + "rate_limited_count": { + "type": "integer" + }, + "rpm": { + "type": "integer" + }, + "updated_at": { + "type": "integer" + } + } + }, + "internal_api.TokenStats": { + "type": "object", + "properties": { + "input": { + "type": "integer" + }, + "output": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "internal_api.TokenView": { + "type": "object", + "properties": { + "allow_ips": { + "type": "string" + }, + "created_at": { + "type": "integer" + }, + "default_namespace": { + "type": "string" + }, + "deny_ips": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "group": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "issued_at_epoch": { + "type": "integer" + }, + "issued_by": { + "type": "string" + }, + "last_accessed_at": { + "type": "string" + }, + "model_limits": { + "type": "string" + }, + "model_limits_enabled": { + "type": "boolean" + }, + "namespaces": { + "type": "string" + }, + "quota_limit": { + "type": "integer" + }, + "quota_reset_at": { + "type": "string" + }, + "quota_reset_type": { + "type": "string" + }, + "quota_used": { + "type": "integer" + }, + "request_count": { + "type": "integer" + }, + "scopes": { + "type": "string" + }, + "status": { + "type": "string" + }, + "updated_at": { + "type": "integer" + }, + "used_tokens": { + "type": "integer" + } + } + }, + "internal_api.TopModelStat": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "requests": { + "type": "integer" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.UpdateAccessRequest": { + "type": "object", + "properties": { + "default_namespace": { + "type": "string" + }, + "namespaces": { + "type": "array", + "items": { + "type": "string" + } + }, + "propagate_to_keys": { + "type": "boolean" + } + } + }, + "internal_api.UpdateAlertThresholdsRequest": { + "type": "object", + "properties": { + "global_qps": { + "type": "integer" + }, + "master_rpd": { + "type": "integer" + }, + "master_rpm": { + "type": "integer" + }, + "master_tpd": { + "type": "integer" + }, + "master_tpm": { + "type": "integer" + }, + "min_rpm_requests_1m": { + "type": "integer" + }, + "min_tpm_tokens_1m": { + "type": "integer" + } + } + }, + "internal_api.UpdateMasterRequest": { + "type": "object", + "properties": { + "global_qps": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "max_child_keys": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "propagate_to_keys": { + "type": "boolean" + } + } + }, + "internal_api.UpdateNamespaceRequest": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "internal_api.UpdateTokenRequest": { + "type": "object", + "properties": { + "allow_ips": { + "type": "string" + }, + "deny_ips": { + "type": "string" + }, + "expires_at": { + "type": "string" + }, + "model_limits": { + "type": "string" + }, + "model_limits_enabled": { + "type": "boolean" + }, + "scopes": { + "type": "string" + }, + "status": { + "description": "active/suspended", + "type": "string" + } + } + }, + "internal_api.WhoamiResponse": { + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "example": 1703505600 + }, + "default_namespace": { + "type": "string", + "example": "default" + }, + "epoch": { + "type": "integer", + "example": 1 + }, + "global_qps": { + "type": "integer", + "example": 100 + }, + "group": { + "type": "string", + "example": "default" + }, + "id": { + "description": "Master fields (only present when type is \"master\")", + "type": "integer", + "example": 1 + }, + "issued_at_epoch": { + "type": "integer", + "example": 1 + }, + "issued_by": { + "type": "string", + "example": "master" + }, + "master_id": { + "description": "Key fields (only present when type is \"key\")", + "type": "integer", + "example": 1 + }, + "max_child_keys": { + "type": "integer", + "example": 5 + }, + "name": { + "type": "string", + "example": "tenant-a" + }, + "namespaces": { + "type": "string", + "example": "default,ns1" + }, + "role": { + "description": "Admin fields (only present when type is \"admin\")", + "type": "string", + "example": "admin" + }, + "scopes": { + "type": "string", + "example": "chat:write" + }, + "status": { + "type": "string", + "example": "active" + }, + "type": { + "description": "Type of the authenticated identity: \"admin\", \"master\", or \"key\"", + "type": "string", + "example": "master" + }, + "updated_at": { + "type": "integer", + "example": 1703505600 + } + } + }, + "internal_api.apiKeyStatsFlushEntry": { + "type": "object", + "properties": { + "api_key_id": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "success_requests": { + "type": "integer" + } + } + }, + "internal_api.apiKeyStatsFlushRequest": { + "type": "object", + "properties": { + "keys": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.apiKeyStatsFlushEntry" + } + } + } + }, + "internal_api.refreshModelRegistryRequest": { + "type": "object", + "properties": { + "ref": { + "type": "string" + } + } + }, + "internal_api.reportAlertEntry": { + "type": "object", + "required": [ + "severity", + "title", + "type" + ], + "properties": { + "fingerprint": { + "type": "string" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "severity": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "internal_api.reportAlertsRequest": { + "type": "object", + "required": [ + "alerts" + ], + "properties": { + "alerts": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.reportAlertEntry" + } + } + } + }, + "internal_api.reportAlertsResponse": { + "type": "object", + "properties": { + "accepted": { + "type": "integer" + }, + "deduplicated": { + "type": "integer" + }, + "errors": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "internal_api.statsFlushEntry": { + "type": "object", + "properties": { + "last_accessed_at": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "token_hash": { + "type": "string" + }, + "tokens": { + "type": "integer" + } + } + }, + "internal_api.statsFlushRequest": { + "type": "object", + "properties": { + "keys": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.statsFlushEntry" + } + } + } + }, + "modelcap.Meta": { + "type": "object", + "properties": { + "checksum": { + "type": "string" + }, + "source": { + "type": "string" + }, + "updated_at": { + "type": "string" + }, + "upstream_ref": { + "type": "string" + }, + "upstream_url": { + "type": "string" + }, + "version": { + "type": "string" + } + } + }, + "modelcap.Model": { + "type": "object", + "properties": { + "context_window": { + "type": "integer" + }, + "cost_per_token": { + "type": "number" + }, + "kind": { + "type": "string" + }, + "max_output_tokens": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "supports_fim": { + "type": "boolean" + }, + "supports_functions": { + "type": "boolean" + }, + "supports_stream": { + "type": "boolean" + }, + "supports_tool_choice": { + "type": "boolean" + }, + "supports_vision": { + "type": "boolean" + } + } + } + }, + "securityDefinitions": { + "AdminAuth": { + "description": "Type \"Bearer\" followed by a space and the admin token. Example: Bearer admin123", + "type": "apiKey", + "name": "Authorization", + "in": "header" + }, + "MasterAuth": { + "description": "Type \"Bearer\" followed by a space and the master key. Example: Bearer sk-xxx", + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } +} \ No newline at end of file diff --git a/docs/swagger/swagger.yaml b/docs/swagger/swagger.yaml new file mode 100644 index 0000000..55490a2 --- /dev/null +++ b/docs/swagger/swagger.yaml @@ -0,0 +1,4031 @@ +basePath: / +definitions: + gin.H: + additionalProperties: {} + type: object + github_com_ez-api_ez-api_internal_dto.APIKeyDTO: + properties: + access_token: + type: string + account_id: + type: string + api_key: + type: string + auto_ban: + type: boolean + ban_reason: + type: string + ban_until: + type: string + expires_at: + type: string + group_id: + type: integer + project_id: + type: string + refresh_token: + type: string + status: + type: string + weight: + type: integer + type: object + github_com_ez-api_ez-api_internal_dto.BindingDTO: + properties: + group_id: + type: integer + namespace: + type: string + public_model: + type: string + selector_type: + type: string + selector_value: + type: string + status: + type: string + weight: + type: integer + type: object + github_com_ez-api_ez-api_internal_dto.ModelDTO: + properties: + context_window: + type: integer + cost_per_token: + type: number + kind: + type: string + max_output_tokens: + type: integer + name: + type: string + supports_fim: + type: boolean + supports_functions: + type: boolean + supports_tool_choice: + type: boolean + supports_vision: + type: boolean + type: object + github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO: + properties: + base_url: + type: string + google_location: + type: string + google_project: + type: string + headers_profile: + type: string + models: + items: + type: string + type: array + name: + type: string + static_headers: + type: string + status: + type: string + type: + type: string + type: object + github_com_ez-api_ez-api_internal_model.APIKey: + properties: + access_token: + type: string + account_id: + type: string + api_key: + type: string + auto_ban: + type: boolean + ban_reason: + type: string + ban_until: + type: string + createdAt: + type: string + deletedAt: + $ref: '#/definitions/gorm.DeletedAt' + expires_at: + type: string + failure_rate: + type: number + failure_requests: + type: integer + group_id: + type: integer + id: + type: integer + project_id: + type: string + status: + type: string + success_rate: + type: number + success_requests: + type: integer + total_requests: + type: integer + updatedAt: + type: string + weight: + type: integer + type: object + github_com_ez-api_ez-api_internal_model.Binding: + properties: + createdAt: + type: string + deletedAt: + $ref: '#/definitions/gorm.DeletedAt' + group_id: + type: integer + id: + type: integer + namespace: + type: string + public_model: + type: string + selector_type: + type: string + selector_value: + type: string + status: + type: string + updatedAt: + type: string + weight: + type: integer + type: object + github_com_ez-api_ez-api_internal_model.LogRecord: + properties: + audit_reason: + type: string + client_ip: + type: string + createdAt: + type: string + deletedAt: + $ref: '#/definitions/gorm.DeletedAt' + error_message: + type: string + group: + type: string + id: + type: integer + key_id: + type: integer + latency_ms: + type: integer + master_id: + type: integer + model: + type: string + provider_id: + type: integer + provider_name: + type: string + provider_type: + type: string + request_body: + description: optional, only when audit triggered + type: string + request_size: + type: integer + response_body: + description: optional, only when audit triggered + type: string + response_size: + type: integer + status_code: + type: integer + tokens_in: + type: integer + tokens_out: + type: integer + updatedAt: + type: string + type: object + github_com_ez-api_ez-api_internal_model.Model: + properties: + context_window: + type: integer + cost_per_token: + type: number + createdAt: + type: string + deletedAt: + $ref: '#/definitions/gorm.DeletedAt' + id: + type: integer + kind: + type: string + max_output_tokens: + type: integer + name: + type: string + supports_fim: + type: boolean + supports_functions: + type: boolean + supports_tool_choice: + type: boolean + supports_vision: + type: boolean + updatedAt: + type: string + type: object + github_com_ez-api_ez-api_internal_model.Namespace: + properties: + createdAt: + type: string + deletedAt: + $ref: '#/definitions/gorm.DeletedAt' + description: + type: string + id: + type: integer + name: + type: string + status: + type: string + updatedAt: + type: string + type: object + github_com_ez-api_ez-api_internal_model.ProviderGroup: + properties: + base_url: + type: string + createdAt: + type: string + deletedAt: + $ref: '#/definitions/gorm.DeletedAt' + failure_rate: + type: number + failure_requests: + type: integer + google_location: + type: string + google_project: + type: string + headers_profile: + type: string + id: + type: integer + models: + description: comma-separated list of supported models + type: string + name: + type: string + static_headers: + type: string + status: + type: string + success_rate: + type: number + success_requests: + type: integer + total_requests: + type: integer + type: + description: openai, anthropic, gemini + type: string + updatedAt: + type: string + type: object + github_com_ez-api_ez-api_internal_service.LogWebhookConfig: + properties: + cooldown_seconds: + type: integer + enabled: + type: boolean + secret: + type: string + status_code_threshold: + type: integer + threshold: + type: integer + url: + type: string + window_seconds: + type: integer + type: object + github_com_ez-api_ez-api_internal_service.ModelRegistryCheckResult: + properties: + current_upstream_ref: + type: string + current_version: + type: string + enabled: + type: boolean + latest_version: + type: string + needs_refresh: + type: boolean + upstream_ref: + type: string + type: object + github_com_ez-api_ez-api_internal_service.ModelRegistryStatus: + properties: + cache_current: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.modelRegistryFile' + cache_prev: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.modelRegistryFile' + enabled: + type: boolean + last_error: + type: string + last_refresh_at: + type: integer + models_dev_ref: + type: string + models_dev_url: + type: string + redis_meta: + additionalProperties: + type: string + type: object + type: object + github_com_ez-api_ez-api_internal_service.modelRegistryFile: + properties: + meta: + $ref: '#/definitions/modelcap.Meta' + models: + additionalProperties: + $ref: '#/definitions/modelcap.Model' + type: object + type: object + gorm.DeletedAt: + properties: + time: + type: string + valid: + description: Valid is true if Time is not NULL + type: boolean + type: object + internal_api.APIKeyStatsSummaryResponse: + properties: + failure_rate: + type: number + failure_requests: + type: integer + success_rate: + type: number + success_requests: + type: integer + total_requests: + type: integer + type: object + internal_api.AboutResponse: + properties: + description: + example: High-performance LLM API gateway + type: string + name: + example: EZ-API Gateway + type: string + repository: + example: https://github.com/ez-api/ez-api + type: string + version: + example: 0.1.0 + type: string + type: object + internal_api.AccessResponse: + properties: + default_namespace: + type: string + namespaces: + items: + type: string + type: array + type: object + internal_api.AckAlertRequest: + properties: + acked_by: + type: string + type: object + internal_api.AdminUsageStatsResponse: + properties: + active_masters: + type: integer + by_master: + items: + $ref: '#/definitions/internal_api.MasterUsageAgg' + type: array + by_provider: + items: + $ref: '#/definitions/internal_api.ProviderUsageAgg' + type: array + period: + type: string + total_masters: + type: integer + total_requests: + type: integer + total_tokens: + type: integer + type: object + internal_api.AlertStats: + properties: + acknowledged: + type: integer + active: + type: integer + critical: + type: integer + info: + type: integer + resolved: + type: integer + total: + type: integer + warning: + type: integer + type: object + internal_api.AlertThresholdView: + properties: + global_qps: + type: integer + master_rpd: + type: integer + master_rpm: + type: integer + master_tpd: + type: integer + master_tpm: + type: integer + min_rpm_requests_1m: + type: integer + min_tpm_tokens_1m: + type: integer + updated_at: + type: integer + type: object + internal_api.AlertView: + properties: + acked_at: + type: integer + acked_by: + type: string + created_at: + type: integer + expires_at: + type: integer + id: + type: integer + message: + type: string + metadata: + type: string + related_id: + type: integer + related_name: + type: string + related_type: + type: string + resolved_at: + type: integer + severity: + type: string + status: + type: string + title: + type: string + type: + type: string + updated_at: + type: integer + type: object + internal_api.BatchActionRequest: + properties: + action: + type: string + ids: + items: + type: integer + type: array + status: + type: string + type: object + internal_api.BatchResponse: + properties: + action: + type: string + failed: + items: + $ref: '#/definitions/internal_api.BatchResult' + type: array + success: + items: + type: integer + type: array + type: object + internal_api.BatchResult: + properties: + error: + type: string + id: + type: integer + type: object + internal_api.CountStats: + properties: + active: + type: integer + total: + type: integer + type: object + internal_api.CreateAlertRequest: + properties: + expires_at: + type: integer + message: + type: string + metadata: + type: string + related_id: + type: integer + related_name: + type: string + related_type: + type: string + severity: + type: string + title: + type: string + type: + type: string + required: + - severity + - title + - type + type: object + internal_api.CreateMasterRequest: + properties: + global_qps: + type: integer + group: + type: string + max_child_keys: + type: integer + name: + type: string + required: + - group + - name + type: object + internal_api.DashboardSummaryResponse: + properties: + keys: + $ref: '#/definitions/internal_api.CountStats' + latency: + $ref: '#/definitions/internal_api.LatencyStats' + masters: + $ref: '#/definitions/internal_api.CountStats' + period: + type: string + provider_keys: + $ref: '#/definitions/internal_api.ProviderKeyStats' + requests: + $ref: '#/definitions/internal_api.RequestStats' + tokens: + $ref: '#/definitions/internal_api.TokenStats' + top_models: + items: + $ref: '#/definitions/internal_api.TopModelStat' + type: array + updated_at: + type: integer + type: object + internal_api.DeleteLogsRequest: + properties: + before: + type: string + key_id: + type: integer + model: + type: string + type: object + internal_api.DeleteLogsResponse: + properties: + deleted_count: + type: integer + type: object + internal_api.GroupedStatsItem: + properties: + avg_latency_ms: + type: number + count: + type: integer + date: + description: For group_by=day + type: string + hour: + description: For group_by=hour + type: string + minute: + description: For group_by=minute + type: string + model: + description: For group_by=model + type: string + month: + description: For group_by=month + type: string + tokens_in: + type: integer + tokens_out: + type: integer + type: object + internal_api.GroupedStatsResponse: + properties: + items: + items: + $ref: '#/definitions/internal_api.GroupedStatsItem' + type: array + type: object + internal_api.IssueChildKeyRequest: + properties: + allow_ips: + type: string + deny_ips: + type: string + expires_at: + type: string + group: + type: string + model_limits: + type: string + model_limits_enabled: + type: boolean + scopes: + type: string + type: object + internal_api.KeyUsageStat: + properties: + key_id: + type: integer + requests: + type: integer + tokens: + type: integer + type: object + internal_api.LatencyStats: + properties: + avg_ms: + type: number + type: object + internal_api.ListAlertsResponse: + properties: + items: + items: + $ref: '#/definitions/internal_api.AlertView' + type: array + limit: + type: integer + offset: + type: integer + total: + type: integer + type: object + internal_api.ListLogsResponse: + properties: + items: + items: + $ref: '#/definitions/internal_api.LogView' + type: array + limit: + type: integer + offset: + type: integer + total: + type: integer + type: object + internal_api.ListMasterLogsResponse: + properties: + items: + items: + $ref: '#/definitions/internal_api.MasterLogView' + type: array + limit: + type: integer + offset: + type: integer + total: + type: integer + type: object + internal_api.LogStatsResponse: + properties: + avg_latency_ms: + type: number + by_status: + additionalProperties: + format: int64 + type: integer + type: object + tokens_in: + type: integer + tokens_out: + type: integer + total: + type: integer + type: object + internal_api.LogView: + properties: + audit_reason: + type: string + client_ip: + type: string + created_at: + type: integer + error_message: + type: string + group: + type: string + id: + type: integer + key_id: + type: integer + latency_ms: + type: integer + model: + type: string + provider_id: + type: integer + provider_name: + type: string + provider_type: + type: string + request_body: + type: string + request_size: + type: integer + response_size: + type: integer + status_code: + type: integer + tokens_in: + type: integer + tokens_out: + type: integer + type: object + internal_api.ManageMasterRequest: + properties: + action: + description: freeze/unfreeze + type: string + required: + - action + type: object + internal_api.MasterLogView: + properties: + created_at: + type: integer + error_message: + type: string + group: + type: string + id: + type: integer + key_id: + type: integer + latency_ms: + type: integer + model: + type: string + request_size: + type: integer + response_size: + type: integer + status_code: + type: integer + tokens_in: + type: integer + tokens_out: + type: integer + type: object + internal_api.MasterRealtimeSummaryView: + properties: + master_id: + type: integer + qps: + type: integer + rate_limited: + type: boolean + type: object + internal_api.MasterRealtimeView: + properties: + qps: + type: integer + qps_limit: + type: integer + rate_limited: + type: boolean + requests: + type: integer + tokens: + type: integer + updated_at: + type: integer + type: object + internal_api.MasterUsageAgg: + properties: + master_id: + type: integer + requests: + type: integer + tokens: + type: integer + type: object + internal_api.MasterUsageStatsResponse: + properties: + by_key: + items: + $ref: '#/definitions/internal_api.KeyUsageStat' + type: array + by_model: + items: + $ref: '#/definitions/internal_api.ModelUsageStat' + type: array + period: + type: string + total_requests: + type: integer + total_tokens: + type: integer + type: object + internal_api.MasterView: + properties: + created_at: + type: integer + default_namespace: + type: string + epoch: + type: integer + global_qps: + type: integer + group: + type: string + id: + type: integer + max_child_keys: + type: integer + name: + type: string + namespaces: + type: string + realtime: + $ref: '#/definitions/internal_api.MasterRealtimeView' + status: + type: string + updated_at: + type: integer + type: object + internal_api.ModelUsageStat: + properties: + model: + type: string + requests: + type: integer + tokens: + type: integer + type: object + internal_api.NamespaceRequest: + properties: + description: + type: string + name: + type: string + status: + type: string + type: object + internal_api.OperationLogView: + properties: + actor: + type: string + client_ip: + type: string + created_at: + type: integer + error_message: + type: string + id: + type: integer + latency_ms: + type: integer + method: + type: string + path: + type: string + query: + type: string + request_id: + type: string + status_code: + type: integer + user_agent: + type: string + type: object + internal_api.ProviderKeyStats: + properties: + active: + type: integer + auto_disabled: + type: integer + suspended: + type: integer + total: + type: integer + type: object + internal_api.ProviderUsageAgg: + properties: + provider_id: + type: integer + provider_name: + type: string + provider_type: + type: string + requests: + type: integer + tokens: + type: integer + type: object + internal_api.RequestStats: + properties: + error_rate: + type: number + failed: + type: integer + success: + type: integer + total: + type: integer + type: object + internal_api.StatusResponse: + properties: + status: + example: ok + type: string + uptime: + example: 72h30m15s + type: string + version: + example: 0.1.0 + type: string + type: object + internal_api.SystemRealtimeView: + properties: + by_master: + items: + $ref: '#/definitions/internal_api.MasterRealtimeSummaryView' + type: array + qps: + type: integer + rate_limited_count: + type: integer + rpm: + type: integer + updated_at: + type: integer + type: object + internal_api.TokenStats: + properties: + input: + type: integer + output: + type: integer + total: + type: integer + type: object + internal_api.TokenView: + properties: + allow_ips: + type: string + created_at: + type: integer + default_namespace: + type: string + deny_ips: + type: string + expires_at: + type: string + group: + type: string + id: + type: integer + issued_at_epoch: + type: integer + issued_by: + type: string + last_accessed_at: + type: string + model_limits: + type: string + model_limits_enabled: + type: boolean + namespaces: + type: string + quota_limit: + type: integer + quota_reset_at: + type: string + quota_reset_type: + type: string + quota_used: + type: integer + request_count: + type: integer + scopes: + type: string + status: + type: string + updated_at: + type: integer + used_tokens: + type: integer + type: object + internal_api.TopModelStat: + properties: + model: + type: string + requests: + type: integer + tokens: + type: integer + type: object + internal_api.UpdateAccessRequest: + properties: + default_namespace: + type: string + namespaces: + items: + type: string + type: array + propagate_to_keys: + type: boolean + type: object + internal_api.UpdateAlertThresholdsRequest: + properties: + global_qps: + type: integer + master_rpd: + type: integer + master_rpm: + type: integer + master_tpd: + type: integer + master_tpm: + type: integer + min_rpm_requests_1m: + type: integer + min_tpm_tokens_1m: + type: integer + type: object + internal_api.UpdateMasterRequest: + properties: + global_qps: + type: integer + group: + type: string + max_child_keys: + type: integer + name: + type: string + propagate_to_keys: + type: boolean + type: object + internal_api.UpdateNamespaceRequest: + properties: + description: + type: string + name: + type: string + status: + type: string + type: object + internal_api.UpdateTokenRequest: + properties: + allow_ips: + type: string + deny_ips: + type: string + expires_at: + type: string + model_limits: + type: string + model_limits_enabled: + type: boolean + scopes: + type: string + status: + description: active/suspended + type: string + type: object + internal_api.WhoamiResponse: + properties: + created_at: + example: 1703505600 + type: integer + default_namespace: + example: default + type: string + epoch: + example: 1 + type: integer + global_qps: + example: 100 + type: integer + group: + example: default + type: string + id: + description: Master fields (only present when type is "master") + example: 1 + type: integer + issued_at_epoch: + example: 1 + type: integer + issued_by: + example: master + type: string + master_id: + description: Key fields (only present when type is "key") + example: 1 + type: integer + max_child_keys: + example: 5 + type: integer + name: + example: tenant-a + type: string + namespaces: + example: default,ns1 + type: string + role: + description: Admin fields (only present when type is "admin") + example: admin + type: string + scopes: + example: chat:write + type: string + status: + example: active + type: string + type: + description: 'Type of the authenticated identity: "admin", "master", or "key"' + example: master + type: string + updated_at: + example: 1703505600 + type: integer + type: object + internal_api.apiKeyStatsFlushEntry: + properties: + api_key_id: + type: integer + requests: + type: integer + success_requests: + type: integer + type: object + internal_api.apiKeyStatsFlushRequest: + properties: + keys: + items: + $ref: '#/definitions/internal_api.apiKeyStatsFlushEntry' + type: array + type: object + internal_api.refreshModelRegistryRequest: + properties: + ref: + type: string + type: object + internal_api.reportAlertEntry: + properties: + fingerprint: + type: string + message: + type: string + metadata: + type: string + related_id: + type: integer + related_name: + type: string + related_type: + type: string + severity: + type: string + title: + type: string + type: + type: string + required: + - severity + - title + - type + type: object + internal_api.reportAlertsRequest: + properties: + alerts: + items: + $ref: '#/definitions/internal_api.reportAlertEntry' + type: array + required: + - alerts + type: object + internal_api.reportAlertsResponse: + properties: + accepted: + type: integer + deduplicated: + type: integer + errors: + items: + type: string + type: array + type: object + internal_api.statsFlushEntry: + properties: + last_accessed_at: + type: integer + requests: + type: integer + token_hash: + type: string + tokens: + type: integer + type: object + internal_api.statsFlushRequest: + properties: + keys: + items: + $ref: '#/definitions/internal_api.statsFlushEntry' + type: array + type: object + modelcap.Meta: + properties: + checksum: + type: string + source: + type: string + updated_at: + type: string + upstream_ref: + type: string + upstream_url: + type: string + version: + type: string + type: object + modelcap.Model: + properties: + context_window: + type: integer + cost_per_token: + type: number + kind: + type: string + max_output_tokens: + type: integer + name: + type: string + supports_fim: + type: boolean + supports_functions: + type: boolean + supports_stream: + type: boolean + supports_tool_choice: + type: boolean + supports_vision: + type: boolean + type: object +host: localhost:8080 +info: + contact: + email: support@swagger.io + name: API Support + url: http://www.swagger.io/support + description: Management API for EZ-API Gateway system. + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + termsOfService: http://swagger.io/terms/ + title: EZ-API Control Plane + version: 0.0.1 +paths: + /about: + get: + description: Returns system metadata for display on an about page + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AboutResponse' + summary: Get system information + tags: + - Public + /admin/alerts: + get: + description: List system alerts with optional filters + parameters: + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: offset + in: query + name: offset + type: integer + - description: filter by status (active, acknowledged, resolved, dismissed) + in: query + name: status + type: string + - description: filter by severity (info, warning, critical) + in: query + name: severity + type: string + - description: filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, + key_expired, provider_down, traffic_spike) + in: query + name: type + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.ListAlertsResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List alerts + tags: + - admin + post: + consumes: + - application/json + description: Create a new system alert + parameters: + - description: Alert data + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.CreateAlertRequest' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/internal_api.AlertView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Create alert + tags: + - admin + /admin/alerts/{id}: + delete: + description: Dismiss an alert (soft delete) + parameters: + - description: Alert ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Dismiss alert + tags: + - admin + get: + description: Get a single alert by ID + parameters: + - description: Alert ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AlertView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get alert + tags: + - admin + /admin/alerts/{id}/ack: + post: + consumes: + - application/json + description: Mark an alert as acknowledged + parameters: + - description: Alert ID + in: path + name: id + required: true + type: integer + - description: Ack data + in: body + name: request + schema: + $ref: '#/definitions/internal_api.AckAlertRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AlertView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Acknowledge alert + tags: + - admin + /admin/alerts/{id}/resolve: + post: + description: Mark an alert as resolved + parameters: + - description: Alert ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AlertView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Resolve alert + tags: + - admin + /admin/alerts/stats: + get: + description: Get alert count statistics by status and severity + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AlertStats' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Alert statistics + tags: + - admin + /admin/alerts/thresholds: + get: + description: Get current alert threshold configuration for traffic spike detection + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AlertThresholdView' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get alert thresholds + tags: + - admin + put: + consumes: + - application/json + description: Update alert threshold configuration for traffic spike detection + parameters: + - description: Threshold configuration + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.UpdateAlertThresholdsRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AlertThresholdView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update alert thresholds + tags: + - admin + /admin/api-keys: + get: + description: List API keys with optional filters + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: filter by group_id + in: query + name: group_id + type: integer + - description: filter by status (active, suspended, auto_disabled, manual_disabled) + in: query + name: status + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List API keys + tags: + - admin + post: + consumes: + - application/json + description: Create an API key for a provider group + parameters: + - description: API key payload + in: body + name: key + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Create an API key + tags: + - admin + /admin/api-keys/{id}: + delete: + description: Delete an API key + parameters: + - description: APIKey ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete API key + tags: + - admin + get: + description: Get an API key by id + parameters: + - description: APIKey ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get API key + tags: + - admin + put: + consumes: + - application/json + description: Update an API key + parameters: + - description: APIKey ID + in: path + name: id + required: true + type: integer + - description: API key payload + in: body + name: key + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update API key + tags: + - admin + /admin/api-keys/batch: + post: + consumes: + - application/json + description: Batch delete or status update for api keys + parameters: + - description: Batch payload + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.BatchActionRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.BatchResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Batch api keys + tags: + - admin + /admin/apikey-stats/summary: + get: + description: Aggregate APIKey success/failure stats across all provider groups + parameters: + - description: Start time (unix seconds) + in: query + name: since + type: integer + - description: End time (unix seconds) + in: query + name: until + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.APIKeyStatsSummaryResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: APIKey stats summary (admin) + tags: + - admin + /admin/bindings: + get: + description: List all configured bindings + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by namespace/public_model + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Binding' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List bindings + tags: + - admin + post: + consumes: + - application/json + description: Create a new (namespace, public_model) binding to a provider group + and selector + parameters: + - description: Binding Info + in: body + name: binding + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.BindingDTO' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Binding' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Create a new binding + tags: + - admin + /admin/bindings/{id}: + delete: + description: Delete a binding by id and rebuild bindings snapshot + parameters: + - description: Binding ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete a binding + tags: + - admin + get: + description: Get a binding by id + parameters: + - description: Binding ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Binding' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get a binding + tags: + - admin + put: + consumes: + - application/json + description: Update an existing binding + parameters: + - description: Binding ID + in: path + name: id + required: true + type: integer + - description: Binding Info + in: body + name: binding + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.BindingDTO' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Binding' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update a binding + tags: + - admin + /admin/bindings/batch: + post: + consumes: + - application/json + description: Batch delete or status update for bindings + parameters: + - description: Batch payload + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.BatchActionRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.BatchResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Batch bindings + tags: + - admin + /admin/dashboard/summary: + get: + description: Returns aggregated metrics for dashboard display including requests, + tokens, latency, masters, keys, and provider keys statistics + parameters: + - description: 'time period: today, week, month, all' + in: query + name: period + type: string + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.DashboardSummaryResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Dashboard summary + tags: + - admin + /admin/features: + get: + description: Returns all feature flags stored in Redis (meta:features) + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List feature flags + tags: + - admin + put: + consumes: + - application/json + description: Updates selected feature flags (meta:features). Values are stored + as strings. + parameters: + - description: Feature map + in: body + name: request + required: true + schema: + type: object + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update feature flags + tags: + - admin + /admin/keys/{id}/access: + get: + description: Returns key default_namespace and namespaces + parameters: + - description: Key ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AccessResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get key access settings + tags: + - admin + put: + consumes: + - application/json + description: Updates key default_namespace and namespaces and syncs to Redis + parameters: + - description: Key ID + in: path + name: id + required: true + type: integer + - description: Access settings + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.UpdateAccessRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AccessResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update key access settings + tags: + - admin + /admin/logs: + delete: + consumes: + - application/json + description: Delete logs before a given timestamp with optional filters + parameters: + - description: Delete filters + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.DeleteLogsRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.DeleteLogsResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete logs (admin) + tags: + - admin + get: + description: List request logs with basic filtering/pagination. Returns full + log records including request_body. + parameters: + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: offset + in: query + name: offset + type: integer + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + - description: key id + in: query + name: key_id + type: integer + - description: route group + in: query + name: group + type: string + - description: model + in: query + name: model + type: string + - description: status code + in: query + name: status_code + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.ListLogsResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List logs (admin) + tags: + - admin + /admin/logs/stats: + get: + description: 'Aggregate log stats with basic filtering. Use group_by param for + grouped statistics (model/day/month/hour/minute). Without group_by returns + LogStatsResponse; with group_by returns GroupedStatsResponse. Note: minute-level + aggregation is limited to 6-hour time ranges.' + parameters: + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + - description: 'group by dimension: model, day, month, hour, minute. Returns + GroupedStatsResponse when specified.' + enum: + - model + - day + - month + - hour + - minute + in: query + name: group_by + type: string + produces: + - application/json + responses: + "200": + description: Grouped stats (when group_by is specified) + schema: + $ref: '#/definitions/internal_api.GroupedStatsResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Log stats (admin) + tags: + - admin + /admin/logs/webhook: + get: + description: Returns current webhook notification config + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get log webhook config + tags: + - admin + put: + consumes: + - application/json + description: Updates webhook notification config + parameters: + - description: Webhook config + in: body + name: request + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.LogWebhookConfig' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update log webhook config + tags: + - admin + /admin/masters: + get: + description: List all master tenants + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by name/group + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/internal_api.MasterView' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List masters + tags: + - admin + post: + consumes: + - application/json + description: Create a new master account (tenant) + parameters: + - description: Master Info + in: body + name: master + required: true + schema: + $ref: '#/definitions/internal_api.CreateMasterRequest' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Create a new master tenant + tags: + - admin + /admin/masters/{id}: + delete: + description: Suspends a master and revokes all existing keys by bumping epoch + and syncing to Redis + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete (revoke) master + tags: + - admin + get: + description: Get a master tenant by id + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get master + tags: + - admin + put: + consumes: + - application/json + description: Update master fields; optionally propagate group to existing keys + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + - description: Update payload + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.UpdateMasterRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update master + tags: + - admin + /admin/masters/{id}/access: + get: + description: Returns master default_namespace and namespaces + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AccessResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get master access settings + tags: + - admin + put: + consumes: + - application/json + description: Updates master default_namespace and namespaces; optionally propagate + to existing keys + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + - description: Access settings + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.UpdateAccessRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AccessResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update master access settings + tags: + - admin + /admin/masters/{id}/keys: + post: + consumes: + - application/json + description: Issue a new access token (child key) for a specified master. The + key still belongs to the master; issuer is recorded as admin for audit. + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + - description: Key Request + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.IssueChildKeyRequest' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "403": + description: Forbidden + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Issue a child key on behalf of a master + tags: + - admin + /admin/masters/{id}/manage: + post: + consumes: + - application/json + description: Freeze or unfreeze a master tenant + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + - description: Action + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.ManageMasterRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Manage master status + tags: + - admin + /admin/masters/{id}/realtime: + get: + description: Return realtime counters for the specified master + parameters: + - description: Master ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterRealtimeView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Master realtime stats (admin) + tags: + - admin + /admin/masters/batch: + post: + consumes: + - application/json + description: Batch delete or status update for masters + parameters: + - description: Batch payload + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.BatchActionRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.BatchResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Batch masters + tags: + - admin + /admin/model-registry/check: + post: + consumes: + - application/json + description: Checks models.dev commit SHA for a ref and indicates whether refresh + is needed (does not apply changes) + parameters: + - description: optional override ref + in: body + name: body + schema: + $ref: '#/definitions/internal_api.refreshModelRegistryRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.ModelRegistryCheckResult' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Check model registry upstream version + tags: + - admin + /admin/model-registry/refresh: + post: + consumes: + - application/json + description: Fetches models.dev, computes per-binding capabilities, and updates + Redis meta:models + parameters: + - description: optional override ref + in: body + name: body + schema: + $ref: '#/definitions/internal_api.refreshModelRegistryRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Refresh model registry from models.dev + tags: + - admin + /admin/model-registry/rollback: + post: + description: Rollback meta:models to previous cached last-good version + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Rollback model registry + tags: + - admin + /admin/model-registry/status: + get: + description: Returns Redis meta and local last-good cache info for model capability + registry + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_service.ModelRegistryStatus' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get model registry status + tags: + - admin + /admin/models: + get: + description: Get a list of all registered models + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by name/kind + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Model' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List all models + tags: + - admin + post: + consumes: + - application/json + description: Register a supported model with its capabilities + parameters: + - description: Model Info + in: body + name: model + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ModelDTO' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Model' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Register a new model + tags: + - admin + /admin/models/{id}: + delete: + description: Delete a model by id + parameters: + - description: Model ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete a model + tags: + - admin + put: + consumes: + - application/json + description: Update an existing model's configuration + parameters: + - description: Model ID + in: path + name: id + required: true + type: integer + - description: Model Info + in: body + name: model + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ModelDTO' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Model' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update a model + tags: + - admin + /admin/models/batch: + post: + consumes: + - application/json + description: Batch delete for models + parameters: + - description: Batch payload + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.BatchActionRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.BatchResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Batch models + tags: + - admin + /admin/namespaces: + get: + description: List all namespaces + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by name/description + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Namespace' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List namespaces + tags: + - admin + post: + consumes: + - application/json + description: Create a namespace for bindings + parameters: + - description: Namespace payload + in: body + name: namespace + required: true + schema: + $ref: '#/definitions/internal_api.NamespaceRequest' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Namespace' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Create namespace + tags: + - admin + /admin/namespaces/{id}: + delete: + description: Delete a namespace and its bindings + parameters: + - description: Namespace ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete namespace + tags: + - admin + get: + description: Get a namespace by id + parameters: + - description: Namespace ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Namespace' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get namespace + tags: + - admin + put: + consumes: + - application/json + description: Update a namespace + parameters: + - description: Namespace ID + in: path + name: id + required: true + type: integer + - description: Update payload + in: body + name: namespace + required: true + schema: + $ref: '#/definitions/internal_api.UpdateNamespaceRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Namespace' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update namespace + tags: + - admin + /admin/operation-logs: + get: + description: List admin operation logs + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by actor/method/path + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/internal_api.OperationLogView' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List operation logs + tags: + - admin + /admin/provider-groups: + get: + description: List all provider groups + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by name/type + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup' + type: array + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: List provider groups + tags: + - admin + post: + consumes: + - application/json + description: Create a provider group definition + parameters: + - description: Provider group payload + in: body + name: group + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Create a provider group + tags: + - admin + /admin/provider-groups/{id}: + delete: + description: Delete a provider group and its api keys/bindings + parameters: + - description: ProviderGroup ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Delete provider group + tags: + - admin + get: + description: Get a provider group by id + parameters: + - description: ProviderGroup ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Get provider group + tags: + - admin + put: + consumes: + - application/json + description: Update a provider group + parameters: + - description: ProviderGroup ID + in: path + name: id + required: true + type: integer + - description: Provider group payload + in: body + name: group + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Update provider group + tags: + - admin + /admin/realtime: + get: + description: Return aggregated realtime counters across all masters + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.SystemRealtimeView' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: System-level realtime stats (admin) + tags: + - admin + /admin/stats: + get: + description: Aggregate request stats across all masters + parameters: + - description: today|week|month|all + in: query + name: period + type: string + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.AdminUsageStatsResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Usage stats (admin) + tags: + - admin + /admin/sync/snapshot: + post: + description: Force full synchronization of DB state to Redis + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Force sync snapshot + tags: + - admin + /auth/whoami: + get: + description: |- + Returns the identity of the authenticated user based on the Authorization header. + Supports Admin Token, Master Key, and Child Key (API Key) authentication. + + Response varies by token type: + - Admin Token: {"type": "admin", "role": "admin"} + - Master Key: {"type": "master", "id": 1, "name": "...", ...} + - Child Key: {"type": "key", "id": 5, "master_id": 1, "issued_by": "master", ...} + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.WhoamiResponse' + "401": + description: Invalid or missing token + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + - MasterAuth: [] + summary: Get current identity + tags: + - auth + /internal/alerts/report: + post: + consumes: + - application/json + description: Internal endpoint for Data Plane to report alerts to Control Plane + parameters: + - description: Alerts to report + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.reportAlertsRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.reportAlertsResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + summary: Report alerts from DP + tags: + - internal + /internal/apikey-stats/flush: + post: + consumes: + - application/json + description: Internal endpoint for flushing accumulated APIKey stats from DP + to CP database + parameters: + - description: Stats to flush + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.apiKeyStatsFlushRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + summary: Flush API key stats + tags: + - internal + /internal/stats/flush: + post: + consumes: + - application/json + description: Internal endpoint for flushing accumulated key usage stats from + DP to CP database + parameters: + - description: Stats to flush + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.statsFlushRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + summary: Flush key stats + tags: + - internal + /logs: + post: + consumes: + - application/json + description: Internal endpoint for ingesting logs from Balancer + parameters: + - description: Log Record + in: body + name: log + required: true + schema: + $ref: '#/definitions/github_com_ez-api_ez-api_internal_model.LogRecord' + produces: + - application/json + responses: + "202": + description: Accepted + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + summary: Ingest logs + tags: + - system + /status: + get: + description: Returns public runtime status information without sensitive data + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.StatusResponse' + summary: Get system status + tags: + - Public + /v1/logs: + get: + description: List request logs for the authenticated master + parameters: + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: offset + in: query + name: offset + type: integer + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + - description: model + in: query + name: model + type: string + - description: status code + in: query + name: status_code + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.ListMasterLogsResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: List logs (master) + tags: + - master + /v1/logs/stats: + get: + description: Aggregate request log stats for the authenticated master + parameters: + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.LogStatsResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Log stats (master) + tags: + - master + /v1/realtime: + get: + description: Return realtime counters for the authenticated master + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterRealtimeView' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Master realtime stats + tags: + - master + /v1/self: + get: + description: Returns master metadata for the authenticated master key + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterView' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Get current master info + tags: + - master + /v1/stats: + get: + description: Aggregate request stats for the authenticated master + parameters: + - description: today|week|month|all + in: query + name: period + type: string + - description: unix seconds + in: query + name: since + type: integer + - description: unix seconds + in: query + name: until + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.MasterUsageStatsResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Usage stats (master) + tags: + - master + /v1/tokens: + get: + description: List child keys issued under the authenticated master + parameters: + - description: page (1-based) + in: query + name: page + type: integer + - description: limit (default 50, max 200) + in: query + name: limit + type: integer + - description: search by group/scopes/namespaces/status + in: query + name: search + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/internal_api.TokenView' + type: array + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: List child keys + tags: + - master + post: + consumes: + - application/json + description: Issue a new access token (child key) for the authenticated master + parameters: + - description: Key Request + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.IssueChildKeyRequest' + produces: + - application/json + responses: + "201": + description: Created + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "403": + description: Forbidden + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Issue a child key + tags: + - master + /v1/tokens/{id}: + delete: + description: Suspends a child key under the authenticated master + parameters: + - description: Token ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/gin.H' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Delete (revoke) child key + tags: + - master + get: + description: Get a child key by id under the authenticated master + parameters: + - description: Token ID + in: path + name: id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.TokenView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Get child key + tags: + - master + put: + consumes: + - application/json + description: Update token scopes/status under the authenticated master + parameters: + - description: Token ID + in: path + name: id + required: true + type: integer + - description: Update payload + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.UpdateTokenRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.TokenView' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/gin.H' + "404": + description: Not Found + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - MasterAuth: [] + summary: Update child key + tags: + - master +securityDefinitions: + AdminAuth: + description: 'Type "Bearer" followed by a space and the admin token. Example: + Bearer admin123' + in: header + name: Authorization + type: apiKey + MasterAuth: + description: 'Type "Bearer" followed by a space and the master key. Example: Bearer + sk-xxx' + in: header + name: Authorization + type: apiKey +swagger: "2.0"