Gres API

Welcome to Gres API, your agentic endpoint layer built with FastAPI, modular tools, secure key authentication, and production-ready Docker deployment.

---

🚀 Live Endpoint

Base URL:
https://api.valgresky.com

Interactive Docs:
https://api.valgresky.com/docs

---

✅ Health Check (No Auth)

curl https://api.valgresky.com/gres/health
# → { "Gres Check": "ok" }

---

🔐 Authenticated Endpoints

All main API endpoints require an X-API-Key header.

Set your .env:

VALGRESKY_API_KEY=sk_valgresky_yourkeyhere

---

/gres/snap – Snap a Page

curl -X POST https://api.valgresky.com/gres/snap \
  -H "X-API-Key: sk_valgresky_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

---

/gres/grab – Crawl a Site or Sitemap

curl -X POST https://api.valgresky.com/gres/grab \
  -H "X-API-Key: sk_valgresky_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://yoursite.com/sitemap.xml"}'

---

/gres/source – List Indexed Sources

curl -X GET https://api.valgresky.com/gres/source \
  -H "X-API-Key: sk_valgresky_yourkeyhere"

---

/gres/ask – Query the Vector Index (RAG)

curl -X POST https://api.valgresky.com/gres/ask \
  -H "X-API-Key: sk_valgresky_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is Valgresky?", "top_k": 3}'

---

🛡️ Security

• API key required for all non-health routes.
• Supabase integration is modular and supports dynamic user validation (future-ready).
• TLS handled via Caddy + Let's Encrypt.

---

🐳 Docker Compose (Production)

version: "3.9"

services:
  gres:
    build: .
    ports:
      - "8051:8051"
    volumes:
      - ./docs:/app/docs
      - ./gres_embeddings:/app/gres_embeddings:ro
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GRES_EMBEDDINGS_PATH=/app/gres_embeddings

---

📂 Structure

/src
  /main.py              # FastAPI app
  /tools/mcp.py         # Shared MCP instance
  /tools/builtin/       # @mcp.tool-decorated agents
  /gres_api/routes.py   # API routes
  /utils                # Supabase + helper utils

---

🧠 MCP Tool Example

from tools.mcp import mcp

@mcp.tool(name="snap")
def snap_tool(url: str):
    ...

---

📝 Generated

Last updated: May 06, 2025
Maintainer: Valgresky

---

🛰️ Stay sharp. Stay agentic.