The .well-known/packos-partner.json discovery spec

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 PackOS partner API, which is in early access. The manifest itself is the stable, published contract; individual surfaces it points to are flagged as live or early access so an agent never assumes a capability that is not yet shipped.

Where it lives, and why .well-known

The manifest is served at https://packos.ai/.well-known/packos-partner.json. 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. That last point is a program promise, not a slogan: partner onboarding is designed to be self-serve for humans and agents alike.

The JSON shape

Here is a realistic example of the manifest. Fields are illustrative of the designed contract; treat the live document as authoritative and always read the status flags rather than assuming a surface is shipped.

{
  "schema": "https://packos.ai/schemas/partner-manifest/v1",
  "version": "1.0",
  "updated": "2026-07-21",
  "program": {
    "name": "PackOS Partner Program",
    "status": "early_access",
    "terms_url": "https://packos.ai/partners.html",
    "docs_url": "https://packos.ai/developers.html"
  },
  "register": {
    "endpoint": "https://packos.ai/v1/partners/register",
    "method": "POST",
    "auth": "none",
    "returns": "sandbox_partner_key",
    "human_in_loop": false,
    "status": "early_access"
  },
  "api": {
    "openapi_url": "https://packos.ai/v1/openapi.json",
    "base_url": "https://packos.ai/v1",
    "auth": "bearer_partner_key",
    "status": "early_access"
  },
  "mcp": {
    "endpoint": "https://mcp.packos.ai",
    "transport": "streamable-http",
    "status": "early_access"
  },
  "embed": {
    "web_component": "",
    "script_url": "https://packos.ai/embed/packos-upload.js",
    "hosted_widget_url": "https://quote.packos.ai",
    "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 runs against the manifest is short. Fetch it, read the register endpoint, obtain a sandbox key, then follow the OpenAPI or MCP pointers to make real calls. Here is the first step in three common runtimes.

# curl — fetch the manifest, then register for a sandbox key
curl -s https://packos.ai/.well-known/packos-partner.json

curl -s -X POST https://packos.ai/v1/partners/register \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","contact":"principal@example.com"}'

// JavaScript — discover, then register
const manifest = await fetch(
  "https://packos.ai/.well-known/packos-partner.json"
).then(r => r.json());

const res = await fetch(manifest.register.endpoint, {
  method: manifest.register.method,
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "my-agent", contact: "principal@example.com" })
});
const { sandbox_partner_key } = await res.json();

# Python — discover, then register
import requests

manifest = requests.get(
    "https://packos.ai/.well-known/packos-partner.json"
).json()

res = requests.post(
    manifest["register"]["endpoint"],
    json={"name": "my-agent", "contact": "principal@example.com"},
)
key = res.json()["sandbox_partner_key"]

Once the agent holds a sandbox key it can read api.openapi_url to drive the headless quote flow, or point an MCP client at mcp.endpoint to use the tools directly. Both routes are covered 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 to POST for a sandbox key, whether a human is in the loop (designed to be false), and what the call returns.
• 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 is honest about maturity by design. Read the per-object status field before you rely on a surface. Today the hosted quote widget and upload component are live — you can embed them and hand a real file off to a quote. The register endpoint, the OpenAPI description, and the MCP endpoint are the designed partner API contract and are in early access; treat their shapes as the intended interface and confirm availability against the live manifest before wiring an agent to them in production.

Because the manifest is versioned (schema and 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. Agents register, embed, and earn on their own; it is genuinely self-serve. 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.