{"openapi":"3.0.3","info":{"title":"GreenOps AI Control Plane","version":"1.0.0-enterprise","description":"Proxy LLM enterprise: PII masking, cache semantica, carbon-aware routing, audit trail EU AI Act, FinOps/ESG."},"servers":[{"url":"https://greenops-ai-proxy.copycomp-ai.workers.dev","description":"Produzione Cloudflare Workers"}],"tags":[{"name":"Chat","description":"Proxy LLM OpenAI-compatible"},{"name":"Analytics","description":"Telemetria FinOps/ESG"},{"name":"Audit","description":"Log immutabili EU AI Act"},{"name":"Monitoring","description":"Health e specifica API"},{"name":"Billing","description":"Webhook Stripe e piano Pro"},{"name":"History","description":"Storico chat persistito su KV"}],"paths":{"/v1/chat/completions":{"post":{"tags":["Chat"],"summary":"Proxy LLM principale (PII, cache, fallback, carbon-aware)","operationId":"createChatCompletion","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."},{"name":"X-User-Role","in":"header","required":false,"schema":{"type":"string","enum":["User","FinOps","Compliance","Admin"]},"description":"Ruolo RBAC. Default `User`."},{"name":"X-User-Tier","in":"header","required":false,"schema":{"type":"string","enum":["free","pro","business","enterprise"]},"description":"Informativo. Il piano effettivo è la licenza KV (`tier` + `monthly_limit`); `X-User-Tier` in richiesta non sblocca i limiti."},{"name":"X-User-Gemini-Key","in":"header","schema":{"type":"string"},"description":"Chiave Gemini del client."},{"name":"X-User-OpenAI-Key","in":"header","schema":{"type":"string"},"description":"Chiave OpenAI del client."},{"name":"X-Local-LLM-Url","in":"header","schema":{"type":"string"},"description":"URL OpenAI-compatible del runtime locale (Ollama/GPU)."},{"name":"X-Webhook-Url","in":"header","schema":{"type":"string"},"description":"Webhook Slack/Teams per alerting."},{"name":"X-Chat-Id","in":"header","schema":{"type":"string","format":"uuid"},"description":"ID conversazione Studio. Se assente, il Worker crea una chat nuova."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Completamento (JSON o SSE se `stream: true`).","headers":{"X-Cache-Status":{"schema":{"type":"string","enum":["HIT","MISS","BYPASS"]}},"X-FinOps-Cost-USD":{"schema":{"type":"string"}},"X-ESG-CO2-Grams":{"schema":{"type":"string"}},"X-PII-Redacted-Count":{"schema":{"type":"string"}},"X-Carbon-Grid-Intensity":{"schema":{"type":"string","example":"45gCO2/kWh"}},"X-Fallback-Triggered":{"schema":{"type":"string"}},"X-Audit-Hash":{"schema":{"type":"string"}},"X-User-Tier":{"schema":{"type":"string","enum":["free","pro","business","enterprise"]}},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"`1000` (Free/giorno), `100000` (Pro/mese), `1000000` (Business/mese), `unlimited` (Enterprise)."},"X-Export-Reports":{"schema":{"type":"string","enum":["true"]},"description":"Presente su Business ed Enterprise: export report ESG/FinOps abilitato."},"X-GreenOps-Chat-Id":{"schema":{"type":"string","format":"uuid"},"description":"Conversazione KV in cui è stato salvato il turno."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Body o chiave provider mancante"},"401":{"description":"X-Proxy-Auth non valido"},"403":{"description":"RBAC o prompt injection bloccata"},"429":{"description":"Quota superata (Free 1.000/giorno, Pro 100k/mese, Business 1M/mese)"}}}},"/v1/chats":{"get":{"tags":["History"],"summary":"Elenco chat salvate per la chiave gateway","operationId":"listChats","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."}],"responses":{"200":{"description":"Lista sommario (id, titolo, preview, timestamp)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatListResponse"}}}},"401":{"description":"X-Proxy-Auth non valido"}}},"post":{"tags":["History"],"summary":"Crea una chat vuota","operationId":"createChat","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"}}}}}},"responses":{"201":{"description":"Chat creata"},"401":{"description":"X-Proxy-Auth non valido"}}}},"/v1/chats/{id}":{"get":{"tags":["History"],"summary":"Messaggi di una chat","operationId":"getChat","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Conversazione completa"},"404":{"description":"Chat assente"}}},"delete":{"tags":["History"],"summary":"Elimina una chat","operationId":"deleteChat","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Eliminata"},"404":{"description":"Chat assente"}}}},"/v1/analytics":{"get":{"tags":["Analytics"],"summary":"Telemetry Dashboard FinOps/ESG","operationId":"getAnalytics","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."},{"name":"X-User-Role","in":"header","required":false,"schema":{"type":"string","enum":["User","FinOps","Compliance","Admin"]},"description":"Ruolo RBAC. Default `User`."}],"responses":{"200":{"description":"Totali KV e serie chartData","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsResponse"}}}},"401":{"description":"X-Proxy-Auth non valido"}}}},"/v1/analytics/reset":{"post":{"tags":["Analytics"],"summary":"Azzera i totali KV (solo Admin)","operationId":"resetAnalytics","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."},{"name":"X-User-Role","in":"header","required":true,"schema":{"type":"string","enum":["User","FinOps","Compliance","Admin"]},"description":"Ruolo RBAC. Default `User`."}],"responses":{"200":{"description":"Reset eseguito"},"401":{"description":"Non autenticato"},"403":{"description":"Ruolo diverso da Admin"}}}},"/v1/audit/logs":{"get":{"tags":["Audit"],"summary":"Audit log immutabile EU AI Act (Compliance / Admin)","operationId":"listAuditLogs","parameters":[{"name":"X-Proxy-Auth","in":"header","required":true,"schema":{"type":"string"},"description":"Chiave di accesso al proxy (bootstrap o chiave provisionata)."},{"name":"X-User-Role","in":"header","required":true,"schema":{"type":"string","enum":["User","FinOps","Compliance","Admin"]},"description":"Ruolo RBAC. Default `User`."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Elenco record firmati SHA-256","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLogsResponse"}}}},"401":{"description":"Non autenticato"},"403":{"description":"Ruolo diverso da Compliance/Admin"}}}},"/v1/health":{"get":{"tags":["Monitoring"],"summary":"Health & telemetry check","operationId":"getHealth","responses":{"200":{"description":"Stato infrastruttura","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/openapi.json":{"get":{"tags":["Monitoring"],"summary":"Specifica OpenAPI 3.0","operationId":"getOpenApi","responses":{"200":{"description":"Documento OpenAPI 3.0.3","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/webhooks/stripe":{"post":{"tags":["Billing"],"summary":"Webhook Stripe: checkout.session.completed emette una chiave Pro","operationId":"stripeWebhook","parameters":[{"name":"Stripe-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"Firma HMAC Stripe (`t=…,v1=…`)."}],"responses":{"200":{"description":"Evento accettato. Su checkout.session.completed include `api_key` `gop_pro_…`.","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"api_key":{"type":"string","example":"gop_pro_ab12"},"email":{"type":"string"},"tier":{"type":"string","example":"pro"},"active":{"type":"boolean"}}}}}},"400":{"description":"JSON Stripe non valido"},"401":{"description":"Firma Stripe non valida"}}}}},"components":{"schemas":{"ChatMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}},"ChatCompletionRequest":{"type":"object","required":["messages"],"properties":{"model":{"type":"string","example":"gemini-3.5-flash","description":"Modello o famiglia (`gpt-*`, `gemini-*`, `local-llama3-8b`, `local-deepseek-r1`)."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"stream":{"type":"boolean","default":false},"context_documents":{"description":"Documenti RAG da comprimere e rerankare.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"chat_id":{"type":"string","format":"uuid","description":"Conversazione KV da aggiornare (alternativa a X-Chat-Id)."}}},"ChatCompletionResponse":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"chat.completion"},"choices":{"type":"array","items":{"type":"object"}},"usage":{"type":"object"}}},"ChatListResponse":{"type":"object","properties":{"chats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"preview":{"type":"string"},"messageCount":{"type":"integer"}}}}}},"AnalyticsResponse":{"type":"object","properties":{"totalCostSaved":{"type":"number"},"totalCo2Saved":{"type":"number"},"totalHits":{"type":"integer"},"totalMisses":{"type":"integer"},"hitRate":{"type":"number"},"totalPiiRedacted":{"type":"integer"},"chartData":{"type":"array","items":{"type":"object"}}}},"AuditLogsResponse":{"type":"object","properties":{"count":{"type":"integer"},"logs":{"type":"array","items":{"$ref":"#/components/schemas/AuditRecord"}}}},"AuditRecord":{"type":"object","properties":{"timestamp":{"type":"integer"},"requestId":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string"},"model":{"type":"string"},"promptTokens":{"type":"integer"},"completionTokens":{"type":"integer"},"costUsd":{"type":"number"},"co2Grams":{"type":"number"},"piiCount":{"type":"integer"},"jailbreakBlocked":{"type":"boolean"},"provider":{"type":"string"},"hash":{"type":"string"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"operational"},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string","example":"1.0.0-enterprise"},"checks":{"type":"object","properties":{"kv_storage":{"type":"string","example":"connected"},"gemini_gateway":{"type":"string","example":"ready"},"openai_gateway":{"type":"string","example":"ready"}}},"active_features":{"type":"array","items":{"type":"string"},"example":["pii_masking","cache_hit_routing","carbon_aware","audit_logging"]}}}}}}