{
  "schema": "webmcp.discovery.v1",
  "publisher": "PurposeBot",
  "name": "PurposeBot Machine Discovery",
  "standards_note": "PurposeBot machine-discovery metadata. The /.well-known/webmcp URL is a PurposeBot compatibility endpoint, not the official WebMCP page API; current WebMCP drafts use page-level document.modelContext tools and HTML/form annotations.",
  "official_webmcp": {
    "claim": "not_official_webmcp_compliance",
    "page_api": "document.modelContext",
    "spec_url": "https://webmachinelearning.github.io/webmcp/",
    "chrome_docs_url": "https://developer.chrome.com/docs/ai/webmcp"
  },
  "homepage": "https://purposebot.ai",
  "registry_url": "https://purposebot.ai/api/webmcp/registry.json",
  "agent_registry_url": "https://purposebot.ai/api/agents/registry.json",
  "alternate_registry_urls": [
    "https://purposebot.ai/webmcp.json",
    "https://purposebot.ai/.well-known/webmcp"
  ],
  "agent_quickstart": {
    "version": "purposebot.agent_discovery.v2",
    "docs_url": "https://purposebot.ai/agent-discovery-quickstart.json",
    "api_base": "https://purposebot.ai/v1",
    "human_docs_url": "https://purposebot.ai/platform-guide",
    "agent_auth_onboarding_url": "https://purposebot.ai/agent-auth-onboarding.json",
    "discovery": {
      "method": "GET",
      "path": "/v1/search",
      "query_params": {
        "q": "string (required): natural-language intent query",
        "limit": "int (optional, default 20, max 100)",
        "cursor": "string (optional): opaque pagination token returned as next_cursor",
        "search_mode": "optional enum: tool|entity|hybrid (default tool)",
        "tool_type": "optional enum: all|agent|webmcp|mcp|api",
        "trust_filter": "optional enum: any|high|medium|low"
      },
      "candidate_lanes": [
        "tool registry",
        "trusted agent identities",
        "WebMCP/API discovery",
        "commerce listings",
        "vector similarity when enabled"
      ],
      "pagination": {
        "cursor_field": "next_cursor",
        "cursor_is_opaque": true,
        "stop_when": "next_cursor is null"
      },
      "auth": {
        "type": "api_key",
        "header": "X-API-Key",
        "optional_for": ["/v1/search"],
        "required_for": [
          "/v1/ai/search",
          "/v1/broker/handoff",
          "/v1/reports/interaction/pending",
          "/v1/reports/interaction/contracts/issue",
          "/v1/reports/interaction",
          "/v1/reports/interaction/contracts/{contract_id}",
          "/v1/agents/identity/register"
        ],
        "note": "Search is public with tighter limits; protected workflow calls require X-API-Key."
      },
      "response": {
        "top_level_fields": [
          "query",
          "search_mode",
          "results",
          "tools",
          "listings",
          "entities",
          "next_cursor",
          "diagnostics"
        ],
        "result_fields": [
          "result_kind",
          "tool_id",
          "agent_id",
          "agent_role",
          "name",
          "slug",
          "primary_function",
          "purpose_summary",
          "intent_keywords",
          "trust_score",
          "source",
          "candidate_source_type",
          "entity_id",
          "entity_name",
          "entity_domain",
          "url",
          "protocol_class",
          "card_url",
          "homepage_url",
          "last_seen_at",
          "raw_record"
        ],
        "tool_json_location": "result.raw_record.tool_json",
        "fallback_payload_location": "result.raw_record",
        "agent_identity_raw_record_schema": "purposebot.agent.search.v1",
        "agent_identity_raw_record_policy": "For result_kind=agent, result.raw_record is a sanitized public projection that omits issuer, subject, key, backing-owner, and payment-profile material.",
      "freshness_flags": [
        "result.raw_record.is_stale",
        "result.raw_record.refresh_queued"
      ],
      "diagnostics_contracts": {
        "empty_result_reason": {
          "path": "diagnostics.empty_result_reason",
          "schema": "purposebot.search.empty_result_reason.v1",
          "reason_codes": [
            "no_enabled_candidate_lanes",
            "cursor_exhausted",
            "lane_failures",
            "filters_excluded_candidates",
            "query_too_specific",
            "all_lanes_empty",
            "unknown_empty_result"
          ],
          "machine_fields": [
            "reason_code",
            "retryable",
            "retry_guidance",
            "lane_candidate_counts",
            "active_filters",
            "has_more",
            "lane_errors"
          ]
        },
        "source_freshness": {
          "path": "diagnostics.source_freshness",
          "schema": "purposebot.search.source_freshness.v1",
          "statuses": [
            "fresh",
            "warn",
            "stale",
            "not_applicable"
          ],
          "scope": "visible crawl-backed WebMCP, MCP registry, and API candidates",
          "threshold_policy": "warn after the configured crawler recheck window; stale after the configured stale multiplier",
          "machine_fields": [
            "status",
            "measured_result_count",
            "measured_sources",
            "oldest_age_seconds",
            "missing_timestamp_count",
            "recheck_due_result_count",
            "stale_result_count",
            "refresh_queued_count",
            "thresholds"
          ]
        }
      }
    },
      "ranking_notes": [
        "Trusted agent identity results are limited to active trusted or high-trust identities. For result_kind=agent, result.raw_record is a sanitized projection that omits issuer, subject, key, backing-owner, and payment-profile material.",
        "Commerce discovery ranks sellers with seller-side reputation where applicable.",
        "Org-backed listings are exposed only while their business authority is current.",
        "Trust signals decay over time and are recomputed from verified, role-specific evidence."
      ],
      "feedback_contract": {
        "pending_feedback": {
          "method": "POST",
          "path": "/v1/reports/interaction/pending",
          "purpose": "List settlement-backed feedback obligations for the authenticated agent."
        },
        "issue_contract": {
          "method": "POST",
          "path": "/v1/reports/interaction/contracts/issue",
          "purpose": "Create a signed interaction contract token before invoking a tool."
        },
        "settle_report": {
          "method": "POST",
          "path": "/v1/reports/interaction",
          "required_field": "interaction_token",
          "purpose": "Submit settlement-token feedback; only settlement-provenance feedback can move reputation."
        },
        "status_check": {
          "method": "GET",
          "path": "/v1/reports/interaction/contracts/{contract_id}"
        }
      },
      "examples": [
        {
          "request": {
            "method": "GET",
            "path": "/v1/search?q=crm+enrichment&limit=5&search_mode=tool&tool_type=all",
            "headers": {
              "X-API-Key": "<api-key>"
            }
          },
          "next_step": "If next_cursor is non-null, repeat request with cursor=<next_cursor>."
        },
        {
          "request": {
            "method": "GET",
            "path": "/v1/search?q=seller+handoff&limit=5&search_mode=tool&tool_type=agent",
            "headers": {
              "X-API-Key": "<api-key>"
            }
          },
          "next_step": "Use agent_id plus agent_role to decide whether the result is a seller_agent or service_agent counterparty; candidate_source_type identifies the normalized candidate lane."
        }
      ]
    },
    "agent_identity": {
      "hosted_key_dashboard": "https://purposebot.ai/producer/trust",
      "hosted_key_api": {
        "method": "POST",
        "path": "/v1/auth/producer/signing-keys",
        "auth": "producer session plus an existing active producer API key",
        "purpose": "Generate a hosted agent key, register the identity, and receive the private key once."
      },
      "self_managed_registration": {
        "method": "POST",
        "path": "/v1/agents/identity/register",
        "auth": "API key plus signed proof JWT",
        "purpose": "Register an agent identity backed by a self-managed JWKS."
      }
    },
    "trust_claims": {
      "issuer_metadata": "https://api.purposebot.ai/.well-known/purposebot/trust/claims/issuer",
      "jwks": "https://api.purposebot.ai/.well-known/purposebot/trust/claims/jwks.json",
      "claim_status_template": "https://api.purposebot.ai/.well-known/purposebot/trust/claims/{claim_id}/status"
    },
    "business_authority": {
      "static_verifier_template": "https://api.purposebot.ai/.well-known/purposebot/trust/business-agent-authority/{org_id}/{agent_id}?role={role}&purpose={purpose}&amount={amount}&currency={currency}",
      "lookup_template": "https://api.purposebot.ai/.well-known/purposebot/trust/business-agent-authority?business_domain={business_domain}&agent_issuer={agent_issuer}&agent_subject={agent_subject}&role={role}&purpose={purpose}&amount={amount}&currency={currency}",
      "proof_verification": {
        "method": "POST",
        "path": "/.well-known/purposebot/trust/business-agent-authority/proofs/verify",
        "purpose": "Verify live counterparty authority plus agent key control.",
        "required_fields": [
          "role",
          "purpose",
          "nonce",
          "interaction_url",
          "proof_jwt"
        ],
        "coordinate_modes": [
          ["org_id", "agent_id"],
          ["business_domain", "agent_issuer", "agent_subject"]
        ]
      }
    },
    "api_trust": {
      "provider_create": {
        "mcp_tool": "create_api_trust_provider",
        "rest": {
          "method": "POST",
          "path": "/v1/api-trust/providers"
        },
        "purpose": "Register an API provider and receive a one-time event signing secret plus the well-known domain verification payload."
      },
      "provider_verify": {
        "mcp_tool": "verify_api_trust_provider_domain",
        "rest": {
          "method": "POST",
          "path": "/v1/api-trust/providers/{provider_id}/verify-domain"
        },
        "purpose": "Activate a provider after it publishes /.well-known/purposebot-api-trust.json on its domain."
      },
      "decision": {
        "mcp_tool": "request_api_trust_decision",
        "rest": {
          "method": "POST",
          "path": "/v1/api-trust/decision"
        },
        "purpose": "Return allow, throttle, deny, or challenge for an automated API request using provider scope, nonce, optional request hash, and optional agent proof."
      },
      "event": {
        "mcp_tool": "submit_api_trust_event",
        "rest": {
          "method": "POST",
          "path": "/v1/api-trust/events"
        },
        "purpose": "Submit signed, idempotent API-conduct evidence so provider-local and admitted global API-conduct reputation can update."
      },
      "reputation": {
        "mcp_tool": "get_api_trust_reputation",
        "rest": {
          "method": "GET",
          "path": "/v1/api-trust/agents/{agent_id}/reputation?trust_context=api:global"
        },
        "purpose": "Read API-conduct reputation separately from commerce seller/buyer reputation."
      }
    }
  },
  "sitemap_url": "https://purposebot.ai/sitemap.xml",
  "updated_at": "2026-07-03T00:00:00Z",
  "mcp_endpoint": "https://purposebot.ai/mcp"
}