The protocol, in full.

Design principles

Four rules govern every shape on this page. A server that keeps all four is a People API. A server that breaks one isn't.

1. Hand-writable, agent-generable. Every field can be produced from a short natural-language sentence. No required field needs a catalog lookup or a vendor-specific code.
2. Progressive disclosure. The data the registry returns is a function of the caller's relationship to the intent. A stranger sees the least, a transacting vendor sees the most, enforced at the type level — not by documentation.
3. Self-hostable. A single-file SQLite node is a valid deployment. No required external services.
4. Transport-agnostic. HTTP is the default; MCP is the agent integration. Any request/response transport that carries the shapes below is fair game.

Intent schema

An intent is a buyer's published demand. It is the only resource the protocol considers primary — offers, session tokens, and vendors exist to serve intents.

{
  "id": "int_7f3a1b2c",
  "userId": "user-1",
  "category": "plumbing_fixtures",
  "description": "Pink undermount kitchen sink, porcelain, 30 inches",
  "attributes": {
    "material": "porcelain",
    "color": "pink",
    "size_inches": 30,
    "mount": "undermount"
  },
  "constraints": [
    { "type": "material_exclude", "value": "stainless_steel" }
  ],
  "budget": { "min": 200, "max": 400, "currency": "USD" },
  "urgency": "ready_to_buy",
  "location": { "metro": "NYC", "zip": "10013" },
  "tags": ["kitchen", "renovation"],
  "status": "active",
  "autoApproveBelow": 300,
  "createdAt": "2025-11-22T18:04:11Z",
  "expiresAt": null
}

urgency is an enum of browsing, planning, or ready_to_buy — it drives delivery-speed scoring and is considered part of Tier 1.

constraints is an array of objects with type and value fields. The reference server recognizes material_exclude, brand_exclude, and shipping_region_exclude. Matching an _exclude value auto-rejects the offer.

Offer schema

An offer is a vendor's proposed fulfillment of a specific intent. Every field except score is vendor-supplied. Every field including score is returned in API responses.

{
  "id": "off_9a2b4c8d",
  "intentId": "int_7f3a1b2c",
  "vendorId": "ven_abc",
  "price": 280,
  "currency": "USD",
  "deliveryDays": 2,
  "inStock": true,
  "description": "Pink undermount porcelain sink, 30\"",
  "attributes": {
    "material": "porcelain",
    "color": "pink",
    "size_inches": 30,
    "mount": "undermount"
  },
  "matchPercentage": 95,
  "isAlternative": false,
  "alternativeReason": null,
  "score": 82,
  "status": "accepted",
  "createdAt": "2025-11-22T19:11:03Z"
}

Privacy tiers, summarized

Privacy is not a policy decision by the server. It's a type decision — each tier has its own shape. The privacy deep-dive walks through the filter functions; this is the at-a-glance summary.

HTTP surface

Thirteen endpoints grouped by actor. Every endpoint enforces tier visibility on its response shape — no endpoint leaks fields from a higher tier than the caller has unlocked. See the API reference for request bodies and error responses.

Conformance

A People API node is any URL that serves the thirteen endpoints with correctly filtered tier data, validated request bodies, and a scoring engine that respects the auto-accept / auto-reject rules. It need not run on the reference stack — Postgres, Python, Go, or an edge function all qualify if the shapes round-trip.

This is the federation story. A private enterprise registry and a public marketplace can both call themselves People API nodes, and an agent can query both with the same MCP tools. Cross-registry discovery is on the platform roadmap, but a minimum viable federation — agent-side fan-out — already works today.