API docs

A small public read-only API describing Xocket's case studies, so agents and scripts can read our work without scraping the pages.

Basics

The base URL is https://xocket.sh. No authentication, no API keys and no rate limit beyond ordinary edge protection. Every endpoint returns JSON with Content-Type: application/json and permissive CORS, so it can be called from a browser. The machine-readable schema is at /openapi.json.

GET /api/v1/products

Lists every case study. Accepts an optional type query parameter, matching the type shown on the work gallery, such as Dashboard or Mobile App.

curl https://xocket.sh/api/v1/products
curl "https://xocket.sh/api/v1/products?type=Dashboard"

GET /api/v1/products/{slug}

Returns one case study in full, including its challenge, approach, features, outcome and tech stack.

curl https://xocket.sh/api/v1/products/medesk

GET /api/v1/studio

Returns studio-level facts: what Xocket does, the services offered, contact addresses and the canonical URLs of the machine-readable files.

curl https://xocket.sh/api/v1/studio

Errors

Errors are JSON, never HTML, and carry a stable error.code, a human readable message and a hint describing what to do next.

{
  "error": {
    "code": "not_found",
    "message": "No product exists with the slug 'nope'.",
    "hint": "List available products at /api/products",
    "status": 404
  }
}

Versioning

The current version is v1, addressed at /api/v1/*. The unversioned /api/* paths are aliases of the newest version, so integrate against the versioned paths if you want stability. Every response carries an X-API-Version header, and asking for a version that does not exist returns 404 with error.code = unsupported_version.

A version stays available for at least six months after its successor ships. Breaking changes never land inside a version: they arrive as a new one. Once a version is deprecated its responses carry Deprecation: true and a Sunset date, and the replacement is named in the response.

Rate limits

Around 600 requests per 60 seconds per client IP. The counter runs at each Cloudflare edge location rather than globally, so treat the budget as approximate. Every API response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy, so you can self-throttle. Going over returns 429 with Retry-After and error.code = rate_limited.

MCP server

The same data is exposed as MCP tools over Streamable HTTP at https://xocket.sh/mcp, described at /.well-known/mcp. The tools are list_products, get_product and get_studio. No authentication.

curl -X POST https://xocket.sh/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Markdown instead of HTML

Every page on this site also answers in Markdown. Send Accept: text/markdown and you get a Markdown version of the page rather than the HTML one.

curl -H 'Accept: text/markdown' https://xocket.sh/work/medesk