Skip to content
API v1 • 2026-11-19Public Zero-Auth Read-Only120 req / 60s RateLimit HeadersRFC 9457 Problem+JSON

StackOS API, Remote MCP & CLI Documentation

Authored & Maintained by Vishal Singh (Founder & Principal Product Architect • thevishalrajput@gmail.com)

BLUF Summary: StackOS exposes a public, zero-API-key REST Decision Router (POST /api/v1/router), a Streamable HTTP Model Context Protocol server (/api/mcp), an OpenAPI 3.1 specification (/api/openapi.json), and Accept: text/markdown content negotiation across every public page.

1. Versioned Decision Router Endpoint (/api/v1/router)

No authentication token is required for public catalog and routing queries. Pass any English, Hindi, or Hinglish workflow description to receive matched $0 open-source MCP servers, optional paid SaaS APIs, subscription thresholds, and a ready-to-paste .mcp.json bundle.

POST /api/v1/router
curl -sS -X POST https://stackos-ai.vercel.app/api/v1/router \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-11-19" \
  -d '{"query":"automate B2B leads from Typeform to HubSpot with n8n","platform":"claude-code"}'

2. Versioning, Rate Limits & Deprecation

  • Versioning: Major versions are pinned in the URL path (/api/v1/) and echoed via X-API-Version: 2026-11-19.
  • Deprecation Policy: Breaking changes ship under /api/v2/ with a minimum 90-day sunset window signaled via RFC 8594 Deprecation and Sunset headers.
  • Rate Limit Headers: Every API response returns RateLimit-Policy: 120;w=60, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (plus Retry-After on HTTP 429).

3. RFC 9457 Structured JSON Error Model

All 4xx and 5xx API failures return Content-Type: application/problem+json so autonomous agents never have to scrape HTML error pages:

{
  "type": "https://stackos-ai.vercel.app/docs#error-missing_query_field",
  "title": "Missing required query field",
  "status": 400,
  "code": "missing_query_field",
  "detail": "POST /api/v1/router requires a non-empty query string.",
  "resolution": "Include {\"query\":\"<task>\"} in the JSON body."
}

4. Token-Light Markdown Content Negotiation (Accept: text/markdown)

AI search indexers and RAG agents requesting Accept: text/markdown receive a clean Markdown representation with Vary: Accept on any StackOS route (saving 70–90% of context tokens), and Markdown-formatted HTTP 404 responses on invalid paths.

5. Free Tier, Self-Serve Sandbox Token & Scoped OAuth 2.0 Metadata

StackOS includes a permanent $0 Free Public Tier with zero sales-call friction. Agents that require explicit OAuth 2.0 client_credentials tokens or RFC 9728 scoped permissions (catalog:read, router:read, benchmarks:read) can self-provision an instant read-only sandbox token via POST /api/auth/token (discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource).