developers_

Overview

The base URL is https://saatwik.dev/api/v1. Every endpoint is a GET, returns JSON and allows cross-origin requests. The full contract is the OpenAPI 3.1 document at /openapi.json, and /llms.txt explains when to use the site.

Every page also has a Markdown version: request its normal URL with the header Accept: text/markdown.

curl https://saatwik.dev/api/v1/projects?status=building

Endpoints

Each endpoint is an OpenAPI operation; the operation ID is the name to use as a tool or function name.

GET /api/v1/profile   getProfile
GET /api/v1/experience   listExperience
GET /api/v1/projects   listProjects
GET /api/v1/projects/{slug}   getProject

Versioning and deprecation

The version is in the path (/api/v1) and in the API-Version response header. Within a version, changes only add: new endpoints, new response fields, new optional parameters. Anything breaking ships as a new version under a new path.

A superseded version keeps working for at least 6 months after its successor is announced. Deprecation is signalled with a Deprecation header (RFC 9745). Once a retirement date is set the response also carries a Sunset header (RFC 8594), and a Link header with rel="successor-version" points at the replacement.

The unversioned paths /api/profile, /api/experience and /api/projects are deprecated. They answer 308 and redirect to v1, with a Deprecation header.

Rate limits

60 requests per 60 seconds per client. Every response reports the state of the window, so a client can pace itself. Past the limit the API answers 429 with a Retry-After header, in seconds.

The count is kept per server instance, so treat the limit as best-effort.

RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 60
RateLimit-Policy: 60;w=60

Errors

Every failure is JSON with a stable code and a hint for fixing the request. The codes are not_found, method_not_allowed, invalid_parameter and rate_limited.

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "No project has the slug \"x\".",
    "hint": "Use one of the slugs from GET /projects.",
    "documentation": "https://saatwik.dev/openapi.json"
  }
}

Command line

The saatwik package wraps the API for scripts and agents. It prints JSON and honours Retry-After.

npx saatwik projects --status building
npx saatwik project everygpu
npx saatwik page /about