Gres API

What is Gres API?

Gres API is an agentic endpoint layer built with FastAPI, offering modular tools, secure key authentication, and production-ready Docker deployment. It provides endpoints for snapping web pages, crawling sites or sitemaps, listing indexed sources, and querying a vector index via RAG (Retrieval-Augmented Generation).

How to use Gres API?

Set your API key in a .env file as VALGRESKY_API_KEY=sk_valgresky_yourkeyhere. The base URL is https://api.valgresky.com. Use the health check endpoint without authentication (/gres/health). All other endpoints require an X-API-Key header. Invoke endpoints like /gres/snap, /gres/grab, /gres/source, and /gres/ask with appropriate JSON payloads.

Key features of Gres API

• Health check endpoint without authentication
• Snap a page with /gres/snap
• Crawl a site or sitemap with /gres/grab
• List indexed sources via /gres/source
• Query vector index (RAG) with /gres/ask
• API key authentication for all non-health routes

Use cases of Gres API

• Capture a web page snapshot for archiving or analysis
• Index an entire website by crawling its sitemap
• Retrieve metadata about previously indexed sources
• Ask natural‑language questions against the indexed vector store
• Deploy as a containerized service with Docker Compose

FAQ from Gres API

How do I test if the API is running?

Make a GET request to https://api.valgresky.com/gres/health. No authentication is required, and it returns { "Gres Check": "ok" }.

How do I authenticate my requests?

All main API endpoints require an X-API-Key header. Set your key in a .env file as VALGRESKY_API_KEY=sk_valgresky_yourkeyhere and include it in every request.

What endpoints are available?

Four authenticated endpoints: /gres/snap (snap a page), /gres/grab (crawl a site or sitemap), /gres/source (list indexed sources), and /gres/ask (query the vector index with RAG). Plus a public health check at /gres/health.

Can I run Gres API locally with Docker?

Yes. A Docker Compose file is provided that builds the service, exposes port 8051, mounts required directories, and sets environment variables like OPENAI_API_KEY and GRES_EMBEDDINGS_PATH.

What is the MCP integration?

The server includes a shared MCP (Model Context Protocol) instance in /src/tools/mcp.py. Tools like snap are decorated with @mcp.tool and can be invoked as MCP tools, enabling integration with AI agents.