Developer API

Quickstart

# List every post as JSON
curl https://saileshdahal.com.np/api/v1/posts

# One post, metadata
curl https://saileshdahal.com.np/api/v1/posts/flavor-setup-flutter

# The same post as clean markdown
curl https://saileshdahal.com.np/api/v1/posts/flavor-setup-flutter/markdown

# Keyword search
curl "https://saileshdahal.com.np/api/v1/search?q=flutter+flavors"

Authentication

None. Every read endpoint is public. There are no API keys because there is nothing to gate: the data is the blog itself. Do not POST to /api/contact programmatically; it is a human form and rejects scripted submissions.

Versioning and deprecation policy

Versioned by URL path: /api/v1. Additions are non-breaking; breaking changes ship only under /api/v2, never inside v1.

Deprecations are announced at least 12 months ahead, signalled with the RFC 9745 Deprecation header followed by an RFC 8594 Sunset header carrying the removal date. Neither is sent today because nothing is deprecated.

Errors

Every 4xx and 5xx from /api/* is RFC 9457 application/problem+json: a stable machine-readable code, human title and detail, the HTTP status, and usually a hint naming what to try next. Documented codes: not_found, method_not_allowed, invalid_slug, missing_query, unsupported_filter, invalid_form, validation_failed, origin_not_allowed, rate_limited, delivery_failed, internal_error, not_acceptable.

Rate limits

Reads carry a RateLimit-Policy header (draft-ietf-httpapi-ratelimit-headers format) describing advisory fair use of roughly 600 requests per minute per client. It is guidance, not enforcement: reads are not hard-throttled today, so self-throttle to the advertised policy anyway.

Only one limit is enforced: POST /api/contact allows 5 submissions per minute per IP and answers excesses with 429 plus Retry-After: 60.

Endpoints

• GET/api/v1Service index: endpoint list, spec link
• GET/api/v1/posts?tag={tag}All posts as JSON; optional tag filter
• GET/api/v1/posts/{slug}One post as JSON; Accept: text/markdown returns markdown
• GET/api/v1/posts/{slug}/markdownOne post as raw markdown
• GET/api/v1/search?q={query}Keyword search over titles, tags, summaries
• POST/api/mcpMCP server (Streamable HTTP), read-only tools
• POST/api/contactHuman contact form; not for agents

The full contract, including typed response schemas and every error shape, is the OpenAPI document.

Related surfaces

• llms.txt, agent index of every page
• llms-full.txt, the whole corpus in one file
• feed.json, JSON Feed 1.1 index
• MCP server card
• Agent card (A2A)

Markdown twins: append .md to any page URL. Questions: email hi@saileshdahal.com.np.