sfclarity for developers & agents

Read-only, no account, no key request needed. Every surface below is real and live today.

When to use this page

Land here if you're building against sfclarity programmatically — an agent doing live retrieval, a script pulling the events feed, or a developer integrating the API. If you just want the app, go to sfclarity.com/app instead.

Surfaces

• /openapi.json — OpenAPI 3.1 for the two real read-only endpoints (published events, landing-page stats), served directly by Supabase PostgREST under a publishable key that can only ever read published = true rows.
• MCP server — a minimal, unauthenticated, read-only JSON-RPC 2.0 server (search_events, get_event) over the same dataset, deployed as a separate Cloudflare Worker (not this domain): sfclarity-mcp-server.cloudflare-driveway392.workers.dev/mcp. Server card at that Worker's own /.well-known/mcp/server-card.json.
• /llms.txt — full site overview (llmstxt.org convention).
• /AGENTS.md — a short agent-facing guide (distinct from this repo's own internal AGENTS.md).
• GET /e/:id — an agent-only markdown twin per event, including schema.org/Event JSON-LD (:id is a base64url token of the event's canonical URL, minted per event — not a browsable index). A real browser gets redirected to /app instead — this site always links out, never hosts a duplicate event page.
• /.well-known/api-catalog — RFC 9727 API catalog (linkset).
• /.well-known/ai-catalog.json — Agentic Resource Discovery (ARD) entry.
• /.well-known/agent-skills/index.json — agent-skills index entry for the MCP server.

Any page with a markdown twin (this one included) is served via Accept: text/markdown content negotiation — no separate URL needed.

Errors

Two real, already-shipped error shapes, not a hypothetical spec:

• Nonexistent path (including agent-surface probes and any other genuinely missing route): a real 404 status, JSON body { "error": "not_found", "detail": "<path> does not exist on sfclarity.com." } for a non-browser Accept, or a plain-text 404: <path> was not found. See /llms.txt. body for Accept: text/markdown.
• Missing/invalid Supabase API key on the read endpoints: 401 with { "message": "...", "hint": "..." } — see /openapi.json's MissingApiKey response for the live-verified exact shape.

There is no write access anywhere on this API, so there is no error shape for a rejected write — every endpoint is read-only by construction (RLS-gated to published = true), not by convention.

Source

The source repository is private, not publicly browsable. Found a bug or have a feature request? File it at sfsanityorg/sfclarity-issues — a public issue tracker maintained alongside the private source.