Self-sown for Developers & AI Agents

The fastest way in is the Model Context Protocol server at /api/mcp. The initialize handshake, tool listing, and the public read tools (product search and details) work without an API key. Sellers on the Herd plan can also skip writing code entirely: the built-in AI assistant (Settings → AI Assistant) drives this same server conversationally.

Self-serve all the way: the free tier needs no sales contact, new sellers get a 30-day Herd trial, and agents can bootstrap an account and API key programmatically with POST /api/mcp/onboard.

curl -X POST https://self-sown.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "0.1.0" }
    }
  }'

The response carries an mcp-session-id header. Send it back on every follow-up request:

curl -X POST https://self-sown.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session id from the initialize response>" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

To buy, manage orders, or administer a stall, create an API key under Settings → API keys and send it as Authorization: Bearer sk_…. Keys come in three scopes: read, read_write (adds purchasing), and full_access (adds stall/account management).

Prefer plain REST? The Universal Commerce Protocol endpoints expose the same catalog and order pipeline: GET /api/ucp/catalog/search and GET /api/ucp/catalog/lookup read products, and POST /api/ucp/checkout/sessions places an order (requires a read_write key). Response shapes are published as JSON Schema at /api/ucp/schemas/product.json and /api/ucp/schemas/checkout-session.json, the checkout request body is published at /api/ucp/schemas/checkout-session-create.json, and all are referenced from the OpenAPI document.

No MCP runtime? The official CLI wraps the same public catalog and checkout endpoints, and its onboard command mints a free shopping API key:

npx @self-sown/cli onboard --name my-agent --save
npx @self-sown/cli search "raw milk"
npx @self-sown/cli checkout create --product <product-id> --quantity 1

Zero dependencies, JSON in and out. Saved keys are origin-bound and stored at ~/.config/selfsown/config.json (mode 0600). Install from npm or read the source at packages/cli in the repo.

Every error response carries a human-readable error string. Agent-facing endpoints add a stable machine-readable code plus discovery links — branch on code, never on prose. Rate limiting returns 429 with retryAfterSeconds in the body and a Retry-After header. The MCP endpoint speaks JSON-RPC 2.0, so its errors arrive in the JSON-RPC error envelope (error.code / error.message) instead of this REST shape.

{
  "error": "Not found",
  "code": "not_found",
  "status": 404,
  "documentation": {
    "openapi": "https://self-sown.com/openapi.json",
    "mcp": "https://self-sown.com/.well-known/mcp.json",
    "agents": "https://self-sown.com/agents.txt"
  }
}

Unknown routes are content-negotiated: send Accept: text/markdown and a 404 comes back as markdown with links to the documents above; otherwise it comes back as the JSON shape shown here.

• Throttled endpoints return standard RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers (plus X-RateLimit-* mirrors) on every response once a request is accepted for processing, so agents can self-throttle in real time. A request rejected before a limiter runs — for example an unsupported API-Version pin — may omit numeric headers.
• Exceeding a limit returns 429 with a Retry-After header and a retryAfterSeconds body field.
• An endpoint whose normal responses lack numeric rate-limit headers is not throttled — no fictional budgets are advertised. MCP budgets are published in agents.txt (/api/mcp: 600 requests/minute per IP, 300/minute per API key; anonymous initialize: 30/minute); every other throttled endpoint declares its own budget in its response headers.

• The OpenAPI document is semantically versioned (current: 2.x, see info.version and x-versioning-policy).
• Every /api/* response carries an API-Version header with the served major version. Pin a version by sending API-Version: 2; an unsupported value fails closed with a 400 unsupported_api_version error instead of silently serving a different contract.
• Additive changes — new endpoints, new optional fields, new enum values — can ship at any time. Clients must ignore unknown fields.
• Breaking changes — removed or renamed fields or endpoints, newly required parameters — ship only in a new major version.
• Deprecated operations carry the Deprecation response header and, once a removal date is set, the Sunset header (RFC 8594), at least 90 days before removal.