# API docs
Documentation for Xocket's public read-only JSON API: endpoints, error format, and Markdown content negotiation.
[Home](/)
# 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](/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](/.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
```
[Xocket](/)
[About](/about)
[Docs](/docs)
[Contact](/contact)
[llms.txt](/llms.txt)
## 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](/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](/.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
```
---
Source: https://xocket.sh/docs
Site index: https://xocket.sh/llms.txt · Sitemap: https://xocket.sh/sitemap.xml · API: https://xocket.sh/openapi.json
Contact: remotevansh@gmail.com