Developer Resources
Build with the subhbits API
Programmatic access to blog content, newsletter, and contact — designed for agents and developers.
Quickstart
All endpoints are public and require no authentication unless otherwise noted. Rate limits: 100 requests/hour per IP. Respect the RateLimit-* response headers.
# Fetch all blog posts via GraphQL
curl -X POST http://localhost:3000/api/graphql \
-H "Content-Type: application/json" \
-d {"query": "{ getAllPosts { title slug date permalink } }"}
# Get a page as Markdown
curl http://localhost:3000/blog -H "Accept: text/markdown"
# Subscribe to the newsletter
curl -X POST http://localhost:3000/api/newsletter \
-H "Content-Type: application/json" \
-d {"email": "user@example.com"}
# OpenAPI specification
curl http://localhost:3000/api/openapi.jsonAPI Reference
/api/graphqlGraphQL endpoint for querying blog posts, series, tags, and performing semantic search. Supports introspection via GET.
Operations: getAllPosts, getPostBySlug, getPosts, getPostsByTag, getPostsBySeries, getAllSeries, getSeriesBySlug, searchPosts
/api/contactSubmit a contact form message. Requires name, email, and message fields. Optional: subject.
/api/newsletterSubscribe an email to the newsletter. Requires email. Sends a confirmation email before activation. Optional: name, source.
/api/newsletter/confirm?token=...Confirm a newsletter subscription. The token is sent in the confirmation email. Redirects to the newsletter page.
/api/newsletter/unsubscribe?token=...Unsubscribe from the newsletter. The token is included in every newsletter email. Redirects to the newsletter page.
/api/markdown/...Content negotiation for Markdown. Send Accept: text/markdown to any page, or use the dedicated endpoint: /api/markdown/blog/my-post.
/api/openapi.jsonFull OpenAPI 3.1 specification for all REST endpoints. Use this to auto-generate clients or explore the API surface.
Error Responses
All API errors return structured JSON with an error field. Example:
{"error": {"email": "Already subscribed"}}
{"error": {"_form": "Something went wrong. Please try again."}}Unknown API paths return 404 with:
{"error": {"code": "NOT_FOUND", "message": "The requested API endpoint does not exist.", "hint": "Visit /api/openapi.json for the full API specification."}}Rate Limits
Public endpoints are rate-limited to 100 requests per hour per IP. All API responses include these headers:
RateLimit-Policy: 100;w=3600— policy declarationRateLimit-Limit: 100— maximum requests per windowRateLimit-Window: 3600— window in seconds
On a 429 Too Many Requests response, check the Retry-After header for when to retry.
Agent Discovery
Agents and LLMs can discover the subhbits API through these standard mechanisms:
- llms.txt — /llms.txt — human and machine-readable site overview
- OpenAPI — /api/openapi.json — full REST API specification
- Agent Skills — /.well-known/agent-skills/index.json — structured agent capabilities
- API Catalog — /.well-known/api-catalog — JSON Linkset of available APIs
- MCP Server — /.well-known/mcp/server-card.json — Model Context Protocol server card
- Markdown — Send
Accept: text/markdownto any page for a clean text representation - GraphQL — /api/graphql — introspectable GraphQL endpoint for blog content queries
Contact
Questions about the API? Reach out at hi@subhbits.com or use the contact endpoint.