Discovery & the Manifest

How a typed URL becomes an imported library, and every field of the discovery document that makes it possible.

Discovery never touches your server. When a user types any URL for your site —example.com, https://example.com/watch/123, anything — the VC service:

Normalizes it to an origin: forces https://, strips path, query, and fragment, keeps an explicit port if given.
Looks the origin up in the publisher registry. An unregistered origin stops here — the user sees unregistered_publisher.
Retrieves your registered manifest from the registry.

Because the manifest lives in the registry (submitted atregistration, updated by re-submission), your API never serves a public discovery document, and manifest reads cost you nothing.

The manifest

A full-featured manifest looks like this:

manifest.json

{
  "vcp_version": "1",
  "publisher_id": "pub_3f92ka",
  "name": "Example Media",
  "description": "Curated video collections from Example.",
  "icon_url": "https://example.com/images/icon-512.png",
  "api_base": "https://api.example.com/vcp/v1",
  "auth": {
    "type": "pairing",
    "pairing_endpoint": "https://api.example.com/vcp/v1/pair",
    "token_endpoint": "https://api.example.com/vcp/v1/token",
    "user_token": {
      "accepted": true,
      "hint": "Paste your access token from example.com/account/token",
      "url": "https://example.com/account/token"
    }
  },
  "capabilities": ["search", "changes", "progress", "reactions", "playlists"],
  "limits": {
    "max_page_size": 100
  }
}

Fields

Field	Required	Description
`vcp_version`	✅	Highest protocol version you support, a whole integer string like `"1"`.
`publisher_id`	✅	Your platform-issued publisher id. Must match your registry entry.
`name`	✅	Human-readable provider name (≤ 80 chars).
`description`	—	Short description (≤ 200 chars).
`icon_url`	—	Square PNG/JPEG, at least 256 px.
`api_base`	✅	Absolute HTTPS base URL for all API endpoints. May be a different host than your origin (a CDN or API subdomain) — the host is recorded in the registry and covered by the same fetch rules.
`auth`	✅	The auth descriptor — see Authentication.
`capabilities`	✅	Array of capability keywords. Each keyword is matched against its capability convention, which fixes what it applies to, the routes it mounts, the fields it adds, and its scope requirements. Standard keywords: `search`, `changes`, `progress`, `reactions`, `playlists`; vendor extensions use an `x_` prefix. Core endpoints are always implied. Empty array = no optional capabilities.
`limits.max_page_size`	—	Your page-size cap (default 100) — see pagination.

Version negotiation

The protocol major version lives in the URL path (/vcp/v1/). Within a major version changes are strictly additive, and consumers ignore unknown JSON fields — so a v1.2 provider works fine with a v1.0 gateway.

When you eventually move to a new major version, keep older gateways working by listing the versions you still serve:

{
  "vcp_version": "2",
  "previous_versions": [
    { "vcp_version": "1", "api_base": "https://api.example.com/vcp/v1" }
  ]
}

A gateway that only speaks v1 and sees "vcp_version": "2" checksprevious_versions for a v1 entry and uses its api_base. If no mutually supported major version exists, the user sees unsupported_version.

The publisher portal validates vcp_version (and everyprevious_versions entry) at submission time against the platform's supported versions — the current list lives in theRelease Notes, along with what changed in each version. Documentation for superseded versions stays available under a versioned path (e.g. /docs/1.0), switchable from the sidebar.