docs.sh — Agent-Native Documentation

docs.sh

Documentation for agents.

Upload an OpenAPI spec, get back MCP tools, function schemas, and structured context. Docs built for machines to read, not humans to browse.


# Publish docs from an OpenAPI spec
$ curl -X POST https://prim.sh/prim/v1/projects \
    -H "X-402-Payment: $TOKEN" \
    -d '{"name": "my-api", "spec_url": "https://my-api.dns.sh/openapi.json"}'

{
  "id": "prj_n4k8m2",
  "slug": "my-api",
  "human_url": "https://my-api.docs.sh",
  "agent_url": "https://prim.sh/prim/v1/projects/prj_n4k8m2/context",
  "mcp_url": "https://prim.sh/prim/v1/projects/prj_n4k8m2/mcp",
  "openai_url": "https://prim.sh/prim/v1/projects/prj_n4k8m2/functions",
  "endpoints": 12,
  "tools_generated": 12
}

# Agent fetches structured context (not HTML)
$ curl https://prim.sh/prim/v1/projects/prj_n4k8m2/context \
    -H "X-402-Payment: $TOKEN" \
    -d '{"query": "how do I create an instance",
         "max_tokens": 2000}'

{
  "context": "## POST /v1/instances\nCreate a new VPS...",
  "tools": [{"name": "create_instance", "parameters": {...}}],
  "examples": [{"curl": "curl -X POST ...", "response": {...}}]
}

x402 auth

OpenAPI → MCP

OpenAPI → Functions

Semantic search

Context windows

Part of agentstack

The problem

Human docs (today)

HTML pages with navigation, search bars, syntax highlighting, copy buttons. Designed for a human reading in a browser.

Agent docs (docs.sh)

Structured JSON with tool definitions, parameter schemas, examples, and semantic search. Designed for a context window.

Agent reads human docs

Scrape HTML → strip tags → hope the markdown is parseable → stuff 50KB into context → pray it finds the right endpoint.

Agent reads agent docs

Query API → get exactly the relevant context → receive pre-built tool definitions → call the endpoint. 2KB instead of 50KB.

Updating docs

Edit markdown files. Rebuild static site. Deploy. Hope the agent re-scrapes eventually.

Updating docs

Push new OpenAPI spec. Tools, context, and examples regenerate automatically. Agents get the latest on next query.

What agents use it for

Learn any API

Agent encounters a new service. Queries docs.sh for its context. Gets tool definitions + examples. Calls the API correctly on the first try.

Publish their own docs

Agent builds a service on spawn.sh. Publishes its OpenAPI spec to docs.sh. Other agents discover and use it. Machine-readable from day one.

Context-efficient retrieval

Instead of cramming 50KB of docs into context, agent queries for exactly what it needs. "How do I resize an instance?" → 500 tokens of precisely relevant context.

Auto-generated MCP tools

Upload OpenAPI spec → get MCP server config. Any MCP-compatible agent can now use your API as native tools. Zero manual tool definition writing.

Service discovery

Browse the docs.sh registry of x402 services. Agent finds services by capability, not by name. "I need object storage" → store.sh docs.

Version-aware

Docs are versioned with the spec. Agent pins to v1.2 while the service ships v1.3. No breaking changes from doc drift.

Output formats

# Every project gets four output formats automatically:

GET /v1/projects/:id/context
→ Structured context for LLM consumption
→ Semantic search over endpoints, params, examples
→ Token-budgeted: request max_tokens, get exactly that much

GET /v1/projects/:id/mcp
→ MCP tool definitions (Model Context Protocol)
→ Drop into any MCP-compatible agent config
→ Tools auto-update when spec changes

GET /v1/projects/:id/functions
→ OpenAI function calling schema
→ Compatible with any agent framework
→ Includes parameter descriptions + examples

GET /v1/projects/:id/human
→ Traditional HTML docs (for the humans who still exist)
→ Auto-generated from the same spec
→ Hosted at {slug}.docs.sh

API reference

# Projects
POST   /v1/projects                    # Create from OpenAPI spec URL or upload
GET    /v1/projects                    # List your projects
GET    /v1/projects/:id                # Project details
PUT    /v1/projects/:id                # Update spec (triggers regeneration)
DELETE /v1/projects/:id                # Delete project + all versions

# Agent consumption
POST   /v1/projects/:id/context        # Semantic search → structured context
GET    /v1/projects/:id/mcp            # MCP tool definitions
GET    /v1/projects/:id/functions      # OpenAI function schemas
GET    /v1/projects/:id/openapi        # Processed OpenAPI spec

# Registry
GET    /v1/registry                    # Browse public x402 services
GET    /v1/registry/search             # Search by capability

# Versions
GET    /v1/projects/:id/versions       # List spec versions
GET    /v1/projects/:id/v/:ver/context # Pin to specific version

# Webhooks
PUT    /v1/projects/:id/webhook        # Notify on spec change (CI/CD)

Pricing

Resource	Cost	Notes
Publish project	$0.01/mo	Includes hosting + generation
Context query	$0.0005	Per semantic search
MCP/Functions fetch	$0.0001	Per request (cacheable)
Registry listing	Free	Public by default
Human docs hosting	Free	Included with project
Spec regeneration	Free	On each update

An agent querying docs 100 times/day costs $0.05/day. Publishing costs a penny a month.

The problem

Human docs (today)

Agent docs (docs.sh)

Agent reads human docs

Agent reads agent docs

Updating docs

Updating docs

What agents use it for

Learn any API

Publish their own docs

Context-efficient retrieval

Auto-generated MCP tools

Service discovery

Version-aware

Output formats

API reference

Pricing

Documentation is a context window.