# Developers and AI agents Sam's Block is open to AI agents and developers. Everything is public and read-only, and nothing needs a sign-in or API key. ## Quick start ```bash curl "https://www.samsblock.com/api/v1/search?q=reputation&limit=5" ``` ## Ways in | Surface | Address | Use it for | | --- | --- | --- | | REST API | https://www.samsblock.com/api/v1 | List, search and read posts, pages and projects as JSON | | OpenAPI spec | https://www.samsblock.com/openapi.json | Generate a client or function-calling tools | | MCP server | https://www.samsblock.com/mcp | Streamable HTTP. Tools: search_samsblock, get_samsblock_page, list_samsblock_projects | | Docs MCP server | https://www.samsblock.com/docs-mcp | Streamable HTTP. Tools: search_samsblock_docs, get_samsblock_doc, get_samsblock_openapi | | NLWeb ask | https://www.samsblock.com/ask?query=... | Natural-language search, JSON or SSE streaming | | Markdown | add .md to any URL | Clean page text, for example https://www.samsblock.com/about.md | | llms.txt | https://www.samsblock.com/llms.txt | Site guide | ## REST API - `GET /api/v1/search?q=&limit=&cursor=&type=`: ranked search. `type` is post, page or project. - `POST /api/v1/search`: same search with a JSON body `{"q": "...", "limit": 10}`. Send an `Idempotency-Key` header to safely retry. - `GET /api/v1/posts?type=&limit=&cursor=`: newest first. - `GET /api/v1/posts/{slug}`: one item with its full Markdown. - `GET /api/v1/projects`: all projects. Pagination is cursor-based: pass `next_cursor` from the response as `cursor`. Errors are JSON: `{"error": {"code", "message", "status", "docs"}}`. ## Rate limits 120 requests per minute per IP. Every API response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` headers. Over the limit you get HTTP 429 with `Retry-After`. ## Versioning and deprecation policy The version is in the URL (`/api/v1`). Breaking changes get a new version; v1 stays available while it is in use. Before an endpoint is retired, its responses carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with the retirement date, at least 90 days ahead, plus a `Link` to the replacement. No v1 endpoints are deprecated today. ## MCP Add this server to any MCP client: ```json { "mcpServers": { "samsblock": { "type": "http", "url": "https://www.samsblock.com/mcp" } } } ``` Server card: https://www.samsblock.com/.well-known/mcp/server-card.json ## Authentication None. See [auth.md](https://www.samsblock.com/auth.md). ## Discovery files - https://www.samsblock.com/.well-known/ard.json (Agentic Resource Discovery) - https://www.samsblock.com/.well-known/api-catalog (RFC 9727) - https://www.samsblock.com/.well-known/agent-card.json (A2A agent card; endpoint https://www.samsblock.com/a2a, method message/send) - https://www.samsblock.com/.well-known/agent-skills/index.json (agent skills) - https://www.samsblock.com/sitemap.xml and https://www.samsblock.com/schemamap.xml ## Contact Questions or problems: [contact Sam](https://www.samsblock.com/contact/).