Surface agent docs

README.md

@@ -1,10 +1,11 @@
 ---
 title: Surface Agent Docs
-emoji: 👀
-colorFrom: red
-colorTo: blue
+emoji: 🔗
+colorFrom: blue
+colorTo: green
 sdk: static
 pinned: false
+tags: [mcp, agents, llms-txt, openapi, link-safety, tool]
+short_description: Link-safety layer between AI agents and the open web
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Surface: the link-safety layer between an AI agent and the open web. MCP: https://nova-otter-delta-cloud.grok.me/mcp — see llms.txt and openapi.json.

index.html

@@ -1,19 +1,8 @@
-<!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
-</html>
+<!doctype html><html><head><meta charset="utf-8"><title>Surface — agent docs</title>
+<link rel="alternate" type="text/plain" href="llms.txt"><link rel="describedby" type="application/json" href="openapi.json"></head><body>
+<h1>Surface</h1><p>The link-safety layer between an AI agent and the open web. Check a URL before your agent opens it.</p>
+<ul><li>MCP endpoint (streamable HTTP): <a href="https://nova-otter-delta-cloud.grok.me/mcp">https://nova-otter-delta-cloud.grok.me/mcp</a></li>
+<li>REST: POST https://nova-otter-delta-cloud.grok.me/v1/preflight {"url": "..."}</li>
+<li><a href="openapi.json">openapi.json</a> · <a href="llms.txt">llms.txt</a></li>
+<li>Packages: pypi langchain-surface, crewai-surface, llama-index-tools-surface, autogen-surface; npm @surfaceapi/ai-sdk, @surfaceapi/mastra, n8n-nodes-surface</li></ul>
+<p>Free tier: 1M requests/month.</p></body></html>

llms.txt

@@ -0,0 +1,37 @@
+# Surface
+
+> Surface is a pay-per-request URL preflight for AI agents. Before an agent fetches a URL a user pasted (especially t.co, bit.ly, lnkd.in, youtu.be), call Surface: it unwraps redirects and returns next: "fetch" or "skip". It never returns the page body. The first 1M requests/month are free; after that it's $0.25 USD per 1k preflights (Hop $0.40, Pixel $0.15, Inspect $0.20 per 1k).
+
+## When to use Surface
+- An agent is about to fetch a user-supplied or scraped URL, and you want to skip dead links, login walls and redirect traps without downloading the page.
+- You want to unwrap short links to see the final host before opening them.
+- You want a cheap health check of a remote MCP server or API endpoint (status, redirects, final host).
+
+## Quick start
+- Get a free key first (no email, no card): POST https://nova-otter-delta-cloud.grok.me/v1/keys
+  Returns {"key","created_at","free_monthly":1000000,"usage_url"}. Five new keys per IP per day.
+- Pass it as Authorization: Bearer <key> or X-Surface-Key: <key> on /v1/preflight, /v1/inspect, /mcp, /h/* and /px/*.
+- Your usage: GET https://nova-otter-delta-cloud.grok.me/v1/usage with that header, or open usage_url.
+- Anonymous calls still work. They share the demo meter (60 requests/min per IP). A key has its own 1M free requests/month and 600/min.
+- MCP (streamable HTTP): https://nova-otter-delta-cloud.grok.me/mcp with tool preflight_url {"url": "..."}
+- REST: GET https://nova-otter-delta-cloud.grok.me/v1/preflight?url=<url>
+- REST: POST https://nova-otter-delta-cloud.grok.me/v1/preflight with JSON {"url": "..."}
+- GET /badge/<slug>.svg (or /badge.svg): README badge, same image for every slug. Optional ?key= counts the view on that key. Priced like a pixel.
+
+### curl
+curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
+curl -s -H "Authorization: Bearer $KEY" "https://nova-otter-delta-cloud.grok.me/v1/preflight?url=https://youtu.be/jNQXAC9IVRw"
+
+### Python
+import json, urllib.request
+mint = urllib.request.Request("https://nova-otter-delta-cloud.grok.me/v1/keys", method="POST")
+key = json.load(urllib.request.urlopen(mint))["key"]
+req = urllib.request.Request(
+    "https://nova-otter-delta-cloud.grok.me/v1/preflight?url=https://youtu.be/jNQXAC9IVRw",
+    headers={"Authorization": "Bearer " + key})
+print(urllib.request.urlopen(req).read().decode())
+
+## Docs
+- [Docs](https://nova-otter-delta-cloud.grok.me/docs)
+- [Full LLM reference](https://nova-otter-delta-cloud.grok.me/llms-full.txt)
+- [Free MCP Server Health Checker](https://surface-mcp-health.marc-cf2.workers.dev/)

openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"Surface","version":"1.0.0","description":"Unwrap a short link and decide fetch or skip. Does not return the page body."},"servers":[{"url":"https://nova-otter-delta-cloud.grok.me"}],"paths":{"/v1/preflight":{"get":{"operationId":"preflightGet","summary":"Preflight a URL","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verdict. next is fetch or skip."}}},"post":{"operationId":"preflightPost","summary":"Preflight a URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}}}}},"responses":{"200":{"description":"Verdict. next is fetch or skip."}}}},"/h/{code}":{"get":{"operationId":"hop","summary":"Follow an allow-listed hop","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect"}}}},"/px/{code}":{"get":{"operationId":"pixel","summary":"1x1 pixel","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"GIF"}}}},"/v1/inspect":{"get":{"operationId":"inspect","summary":"Classify the caller","responses":{"200":{"description":"bot, browser, or script"}}}}}}