GreenOps AI Studio Docs

Technical documentation for the edge LLM gateway.

← Studio OpenAPI

What is GreenOps AI Studio?

GreenOps AI Studio is a multi-tier SaaS platform designed to proxy and optimize LLM workloads through an OpenAI-compatible AI API Gateway. It applies semantic caching on Cloudflare Workers, FinOps telemetry for token spend and carbon footprint, and a PII anonymization API before requests reach Gemini, OpenAI, or a local GPU runtime. Teams use it as a drop-in proxy alternative to calling provider APIs directly when they need cost control, privacy, and greener inference at the edge.

Introduction & architecture

GreenOps AI is an OpenAI-compatible LLM gateway on Cloudflare Workers. Every chat request is authenticated, PII-masked, optionally served from a semantic KV cache, then routed to Gemini, OpenAI, or a local GPU runtime.

Edge Worker

TypeScript proxy at the Cloudflare PoP. OpenAI-compatible POST /v1/chat/completions.

Semantic cache

WASM prompt hash + KV GREENOPS_CACHE. HIT replies skip the GPU and cost $0 / 0 g CO₂.

PII masking

Emails, cards, phones and tax IDs are anonymized before upstream. Count is returned on X-PII-Redacted-Count.

FinOps / ESG

Response headers expose USD saved, CO₂ avoided, cache HIT/MISS and user tier.

  • Cold path (MISS): trim + hash in WASM, call the LLM, write KV, emit FinOps headers.
  • Hot path (HIT): KV read only — typically tens of milliseconds on the same PoP.
  • Failover: Gemini 429/5xx automatically retries then falls back to OpenAI when configured.
  • Chat history: each completion is appended to Cloudflare KV GREENOPS_CHATS for the gateway key.

Authentication & setup

Protected routes accept the gateway key as Authorization: Bearer <key> or the native header X-Proxy-Auth. For local and sandbox testing use the bootstrap key GreenOpsKey123.

Quick test key

Send Authorization: Bearer GreenOpsKey123 on chat, analytics and audit calls. Paid plans receive a gop_pro_… key after Stripe checkout. Provider keys (Gemini/OpenAI) are optional when the Worker already has server-side credentials.

Gateway authentication headers
HeaderRequiredMeaning
AuthorizationYes*Bearer token. Example: Bearer GreenOpsKey123.
X-Proxy-AuthYes*Equivalent gateway key if you do not send Authorization.
X-User-RoleNoUser (default), FinOps, Compliance, Admin.
X-User-Gemini-KeyNoBring-your-own Gemini key.
X-User-OpenAI-KeyNoBring-your-own OpenAI key.
X-Local-LLM-UrlNoOpenAI-compatible local runtime (Ollama / GPU).
X-Webhook-UrlNoSlack / Teams webhook. POSTed asynchronously via ctx.waitUntil with FinOps (cost, tokens) and ESG (carbon offset) fields.
X-Chat-IdNoExisting conversation UUID. Completions also accept body chat_id.

Copy-ready authentication

Send Authorization: Bearer <TOKEN> on every protected call. The snippets below POST a JSON chat body to /v1/chat/completions. Replace GreenOpsKey123 with your provisioned key in production.

Endpoints & API reference

Proxy URL: https://greenops-ai-proxy.copycomp-ai.workers.dev

Proxy URL
https://greenops-ai-proxy.copycomp-ai.workers.dev
POST · Chat Completions
https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chat/completions
Proxy endpoints on the GreenOps AI gateway
MethodPathAuthPurpose
POST/v1/chat/completionsYesOpenAI-compatible chat (JSON or SSE if stream: true). Persists the turn to KV.
GET/v1/chatsYesList saved conversations for the gateway key
POST/v1/chatsYesCreate an empty chat
GET/v1/chats/:idYesLoad messages of one conversation
DELETE/v1/chats/:idYesDelete a conversation from KV
GET/healthNoUptime probe: status, timestamp, KV semantic cache
GET/v1/healthNoKV cache + analytics, Gemini / OpenAI readiness
GET/v1/analyticsYesFinOps / ESG totals
GET/v1/audit/logsYesEU AI Act audit trail (Compliance / Admin)
POST/v1/webhooks/stripeStripe-SignatureCheckout/invoice → Pro, Business or Enterprise; cancel/unpaid → deactivate
POST/api/webhooks/stripeStripe-SignatureAlias of /v1/webhooks/stripe
GET/v1/openapi.jsonNoOpenAPI 3.0 spec

Chat Completions

POST JSON with model + messages. Every sample sends Authorization: Bearer <TOKEN> and a JSON body. Testing uses GreenOpsKey123; swap in your provisioned key for production. Successful replies persist to KV and return X-GreenOps-Chat-Id.

Copy a language below. Each block is a ready-to-run POST to /v1/chat/completions.

Chat history & sessions

Studio conversations are stored on Cloudflare KV (GREENOPS_CHATS, fallback GREENOPS_CACHE). A D1 database is not required: chat JSON lives in KV. After each successful POST /v1/chat/completions the Worker appends the user/assistant turn, scoped to a SHA-256 of the gateway key. Pass X-Chat-Id (or body chat_id) to continue a session; the response header X-GreenOps-Chat-Id is the conversation to reuse.

  • Per-key isolation: KV keys never store the Bearer secret in plaintext.
  • Limits: 80 chats per user, 200 messages per chat. Title is taken from the first user prompt.
  • Studio sidebar calls GET /v1/chats and GET /v1/chats/:id with the same Bearer token as completions.
  • Bind GREENOPS_CHATS in wrangler.toml. Completions still persist if the binding falls back to GREENOPS_CACHE.
Chat history API on Cloudflare KV
MethodPathAuthPurpose
POST/v1/chat/completionsYesSaves the turn; returns X-GreenOps-Chat-Id
GET/v1/chatsYes{ chats: [{ id, title, updatedAt, preview, messageCount }] }
POST/v1/chatsYesCreate empty chat { title? } → 201
GET/v1/chats/:idYes{ id, title, messages: [{ role, content, at }] }
DELETE/v1/chats/:idYes{ deleted: true, id }

Copy a session example: complete a chat, list history, create an empty chat, reload messages, then delete. Always send Authorization: Bearer <TOKEN>.

cURL · chat session
# 1) First turn — persist a new chat (read X-GreenOps-Chat-Id from the response)
curl -D - https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GreenOpsKey123" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [{"role": "user", "content": "Hello GreenOps"}]
  }'

# 2) Continue the same session
curl https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GreenOpsKey123" \
  -H "X-Chat-Id: CHAT_ID" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "Hello GreenOps"},
      {"role": "assistant", "content": "Hi"},
      {"role": "user", "content": "Continue"}
    ]
  }'

# 3) List, load, create empty, delete
curl https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chats \
  -H "Authorization: Bearer GreenOpsKey123"
curl https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chats/CHAT_ID \
  -H "Authorization: Bearer GreenOpsKey123"
curl -X POST https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chats \
  -H "Authorization: Bearer GreenOpsKey123" \
  -H "Content-Type: application/json" \
  -d '{"title":"New chat"}'
curl -X DELETE https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/chats/CHAT_ID \
  -H "Authorization: Bearer GreenOpsKey123"

Stripe webhooks

Point the Stripe Dashboard endpoint at the URL below. The Worker verifies Stripe-Signature with stripe.webhooks.constructEvent when STRIPE_WEBHOOK_SECRET is set.

POST · Stripe webhook
https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/webhooks/stripe
  • checkout.session.completed and invoice.payment_succeeded activate Pro, Business or Enterprise (email + subscription_id + plan → user record). New users get a welcome email with a password-setup link.
  • Plan is resolved from metadata.plan, Payment Link, price nickname/amount ($29 / $149 / $499+), or STRIPE_PRICE_*.
  • customer.subscription.deleted, subscription.updated with status unpaid/canceled, or a final invoice.payment_failed deactivates access (active: false, profile → Free).
  • Configure POST /v1/webhooks/stripe or POST /api/webhooks/stripe. Alias accepted. No browser CORS is required.
cURL · webhook
curl -X POST https://greenops-ai-proxy.copycomp-ai.workers.dev/v1/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1700000000,v1=…" \
  -d '{"type":"checkout.session.completed","data":{"object":{"customer_email":"dev@acme.com"}}}'

Pricing tiers & quotas

Limits are enforced at the edge. Free is daily + burst; Pro and Business are monthly; Enterprise is unlimited.

GreenOps AI Studio pricing tiers
Plan Price Request limits Features
Free$0/mo1,000 req/day · 30 req/minStandard semantic caching, baseline PII masking, Community & Docs
Pro$29/mo100,000 req/monthPriority processing, real-time ESG/FinOps telemetry, automated PII anonymization
Business$149/mo1,000,000 req/monthESG/FinOps PDF & CSV export, advanced PII rules, priority support
Enterprise$499+/moUnlimitedDedicated Workers & storage, custom ESG audit, 99.9% uptime SLA

Error handling & status codes

The gateway returns JSON errors. Chat quota responses include error.code, error.message and error.upgrade_url.

HTTP status codes returned by the AI gateway
Status Name Typical cause What to do
401UnauthorizedMissing/invalid Bearer or X-Proxy-Auth.Send Authorization: Bearer GreenOpsKey123 (test) or your provisioned key. Check for extra spaces.
429Rate Limit ExceededFree 1,000/day or 30/min; Pro 100k/mo; Business 1M/mo.Wait for Retry-After, or upgrade. Burst resets every 60 seconds.
500Gateway ErrorUnhandled Worker exception or upstream failure after retries.Retry with backoff. Check GET /v1/health. Confirm Gemini/OpenAI keys if the model is cloud-hosted.
404Not FoundUnknown /v1/chats/:id for this gateway key.List chats with GET /v1/chats, then use an id from that payload.
  • 403: RBAC blocked the route (for example Audit requires Compliance/Admin) or prompt injection was rejected.
  • 400: malformed JSON, missing messages[], or a required provider key is absent for that model.
  • SSE: send stream: true. Cache is bypassed on streaming responses.
  • 404 on /v1/chats/:id: the conversation is missing or belongs to another gateway key.

Testing & QA

GreenOps ships an automated suite so the gateway, semantic cache, chat history, and the Studio docs modal stay copy-ready. Backend tests run in Vitest against an in-memory mock Worker (or a live origin when GREENOPS_URL is set). Frontend tests run in Playwright against the static Studio server on port 4173.

  • Install once: npx playwright install chromium (needed for E2E). Vitest is a local npm dependency.
  • Default API tests never call production: tests/helpers/mock-greenops-worker.js mocks completions, KV cache HIT/MISS, and /v1/chats.
  • Point API tests at a live Worker with GREENOPS_URL and optional GREENOPS_AUTH.

Backend · Vitest

tests/api.spec.js covers the OpenAI-compatible gateway: missing Bearer returns 401; a valid key returns 200 with FinOps/ESG headers; an identical prompt is a semantic-cache MISS then HIT; GET/POST/DELETE /v1/chats persist and drop history. Run with npm run test:api (vitest run tests/api.spec.js).

Frontend · Playwright

tests/e2e/docs.spec.js opens Studio, clicks Documentation, fetches same-origin /docs.html without redirect loops, and checks the copyable language tabs (cURL, Python, JavaScript/TypeScript, C#, VB.Net) in English and Italian. Playwright starts node scripts/studio-static.mjs on port 4173. Run with npm run test:e2e.

Quick commands

From the repository root. npm test runs API tests first, then E2E.

Automated test scripts
Command What it runs
npm testRuns all tests
npm run test:apiRuns the API tests
npm run test:e2eRuns the E2E tests
npm · test scripts
npm test
npm run test:api
npm run test:e2e

Contact & support

Reach GreenOps Studio by email. Technical issues go to support; general inquiries to info; Enterprise and commercial requests to sales.