The .well-known/packos-partner.json discovery spec (proposed)

What the manifest is

The PackOS partner manifest is a small JSON document that describes the partner program to a machine. Instead of asking a developer to read a page and copy an endpoint by hand, an agent fetches one well-known URL, parses the response, and discovers everything it needs to participate: where to register, what it can embed, where the API is described, and how commission is calculated. It is the same discovery pattern that robots.txt or security.txt follow — a predictable location an automated client can rely on without being told where to look.

This spec is part of the planned PackOS partner API; the program itself is in early access. The manifest is a proposed contract, not a published file. Its design flags each surface as live, early access, or planned, so an agent never assumes a capability that is not yet shipped.

Where it lives, and why .well-known

The manifest is planned to be served at https://packos.ai/.well-known/packos-partner.json (it is not yet). The /.well-known/ prefix is the IETF-registered convention (RFC 8615) for host-level metadata that machines fetch without guessing at a path. Putting the manifest there means an agent that knows only the domain — packos.ai — can construct the full URL deterministically and fetch it in one request.

A crawler or agent that finds a PackOS embed on a third-party page can walk back to the origin, request the manifest, and learn how to work with the platform directly. No sales call, no form, no scraped documentation. Self-serve onboarding for humans and agents alike is the design goal; today, keys are issued on request.

The JSON shape

Here is an example of the proposed manifest. Fields are illustrative of the designed contract and nothing here is published; once a manifest exists, treat the live document as authoritative and always read the status flags rather than assuming a surface is shipped.

{
  "version": "1.0",
  "program": {
    "name": "PackOS Partner Program",
    "status": "early_access",
    "terms_url": "https://packos.ai/partners.html",
    "docs_url": "https://packos.ai/developers.html"
  },
  "register": {
    "endpoint": null,
    "status": "planned"
  },
  "api": {
    "base_url": "https://packos.ai/api/embed",
    "auth": "partner_key",
    "status": "early_access"
  },
  "mcp": {
    "endpoint": null,
    "status": "planned"
  },
  "embed": {
    "web_component": "<packos-upload key=\"pk_...\"></packos-upload>",
    "script_url": "https://packos.ai/embed/packos-upload.js",
    "hosted_widget_url": "https://packos.ai/quote",
    "status": "live"
  },
  "commission": {
    "model": "hybrid",
    "components": ["bounty_on_qualified_quote", "revshare_on_order"],
    "rates": "published_to_partners_at_signup",
    "attribution_window_days": 60,
    "attribution_basis": "last_touch"
  },
  "payouts": {
    "rails": ["fiat", "usdc"],
    "connect_account_at": "cash_out"
  }
}

The document is intentionally flat and boring. It carries no secrets, no per-partner data, and nothing that changes between requests — it is a public directory, cacheable and safe to fetch repeatedly.

How an agent self-onboards

The flow an agent would run against the manifest is short: fetch it, read the register endpoint, obtain a key, then follow the API or MCP pointers to make real calls. None of that works today, because no manifest or register endpoint is published. Here is the first step as a sketch:

// JavaScript — sketch only. The manifest is not published yet, so this fetch returns 404 today.
const res = await fetch("https://packos.ai/.well-known/packos-partner.json");
if (!res.ok) {
  // not published: fall back to https://packos.ai/partners.html (request early access)
} else {
  const manifest = await res.json();
  if (manifest.register.status === "live") {
    // follow manifest.register.endpoint
  }
}

The keyed upload path that does exist today is described in PackOS for AI agents; further integration notes are in adding packaging quoting to your agent.

Field reference

Every top-level object maps to one thing an agent needs to decide before it acts.

• program — the human-facing name plus links to the full terms and developer docs, and a status flag for the program as a whole.
• register — where an agent would POST for a key once self-registration exists; null and planned until then.
• api — the OpenAPI URL and base URL for the headless quote endpoints, plus the auth scheme (a bearer partner key).
• mcp — the Model Context Protocol endpoint and transport, for agents that speak MCP rather than raw HTTP.
• embed — the <packos-upload> web component and hosted widget an agent can drop into a generated page; the upload and quote happen on PackOS.
• commission — the model in summary form: you earn on real packaging quotes and the orders they turn into, with the attribution window stated. Actual rates are published to partners at signup, not in the public manifest.
• payouts — how earnings pay out: fiat or a USDC wallet. You link a payout account when you're ready to cash out.

What is live, and what is early access

The manifest design is honest about maturity: read the per-object status field before you rely on a surface. Today the upload web component and the hosted quote widget are live, and the partner-keyed upload endpoints behind them (/api/embed/sign and /api/embed/commit) are in early access for partners who have been issued a key. Self-registration, a published partner OpenAPI description, the MCP endpoint, and the manifest file itself are planned, not published.

Because the manifest would be versioned (version), an agent can pin to a schema it understands and degrade gracefully when it sees a version it does not. That is the point of publishing a contract rather than a blog post: the machine reads the contract, not the prose.

The trust boundary

One thing the manifest deliberately does not do is move data or money through the agent. The embed surfaces it advertises are thin: they collect a file and a public partner key and hand off to PackOS. The upload, the AI detection models, and attribution all stay on the platform — the embed never sees them. That is the security story, and it is why a public discovery document is safe to publish in the first place: nothing in it is a secret, and nothing an agent does with it bypasses server-side validation.

The same holds for commission. You earn on real packaging quotes — genuine files that clear detection, not bot traffic — and PackOS confirms each one server-side. Self-serve agent onboarding is the goal; today, keys are issued on request. When it is time to cash out, earnings pay to a connected payout account, in fiat or USDC. The manifest points at these details so an agent knows what to expect from the first request. For the full model, see how an AI agent earns commission with PackOS.