Как читать AiPassport

{
  "canonical_routes": {
    "human_view": "/{passport_id}",
    "json_ld": "/{passport_id}/json",
    "legacy_prefix": "/passport/{passport_id}/... kept for compatibility only",
    "llms_txt": "/{passport_id}/llms.txt",
    "note": "/{passport_id} is the stable short address; its HTML declares the geographic page URL in \u003clink rel=\"canonical\"\u003e."
  },
  "complaint_policy": {
    "confirmed_reports": "Apply trust warning only to the specific passport_id in JSON-LD and llms.txt.",
    "domain_isolation": "Do not punish an entire seller domain or AiPassport.cloud for one passport issue.",
    "unverified_reports": "Private until operator confirms; do not lower public trust automatically."
  },
  "description": "Official digital passports for businesses and specialists. Seller-stated verified passport snapshots for AI search, agents, and crawlers.",
  "endpoints": {
    "directory": "https://aipassport.cloud/api/v1/directory",
    "directory_cities": "https://aipassport.cloud/api/v1/directory/cities",
    "directory_countries": "https://aipassport.cloud/api/v1/directory/countries",
    "directory_sectors": "https://aipassport.cloud/api/v1/directory/sectors",
    "for_agents": "https://aipassport.cloud/for-agents",
    "for_business": "https://aipassport.cloud/for-business",
    "location_offer_search": "https://aipassport.cloud/api/v1/locations/offers/search",
    "mcp": "https://aipassport.cloud/mcp",
    "mcp_clients": "https://aipassport.cloud/mcp",
    "mcp_discovery": "https://aipassport.cloud/.well-known/mcp.json",
    "offer_search": "https://aipassport.cloud/api/v1/offers/search",
    "openapi": "https://aipassport.cloud/openapi.json",
    "platform_index": "https://aipassport.cloud/llms.txt",
    "robots": "https://aipassport.cloud/robots.txt",
    "search": "https://aipassport.cloud/api/v1/search",
    "sitemap": "https://aipassport.cloud/sitemap.xml",
    "well_known_llms": "https://aipassport.cloud/.well-known/llms.txt",
    "wordpress_plugin": "https://aipassport.cloud/api/v1/site-install/wordpress.zip"
  },
  "entity_url_templates": {
    "human_view": "https://aipassport.cloud/{passport_id}",
    "json_ld": "https://aipassport.cloud/{passport_id}/json",
    "legacy_human_view": "https://aipassport.cloud/passport/{passport_id}/view",
    "llms_txt": "https://aipassport.cloud/{passport_id}/llms.txt",
    "site_install_manifest": "https://aipassport.cloud/api/v1/site-install/{passport_id}",
    "site_tag_js": "https://aipassport.cloud/api/v1/site-tag/{passport_id}.js"
  },
  "json_ld_trust_fields": [
    "trustStatus",
    "confirmedTrustIssues",
    "snapshotValidUntil",
    "dataSource",
    "fieldConfidence",
    "complaintPolicy",
    "itemType on offers"
  ],
  "location_offer_search": {
    "coordinates": "latitude and longitude are optional but must be supplied together; without them, no result is called nearest",
    "example": "https://aipassport.cloud/api/v1/locations/offers/search?passport_id={passport_id}\u0026query={url_encoded_question}",
    "geo_filters": "country and city are exact ISO/name and city-ID/name lookups; blank branch geo inherits the passport",
    "max_limit": 50,
    "method": "GET",
    "optional": true,
    "pagination": "No cursor parameter; narrow the filters when more than max_limit matches exist.",
    "purpose": "Search effective prices at physical branches and rank them by distance when coordinates are supplied",
    "rate_limit": "30 requests/minute per IP",
    "required_filters": "At least one of: city, country, brand, passport_id, query",
    "sort": [
      "distance",
      "price_asc",
      "trust"
    ]
  },
  "mcp": {
    "clients": {
      "cursor": {
        "config": {
          "mcpServers": {
            "aipassport": {
              "url": "https://aipassport.cloud/mcp"
            }
          }
        },
        "file": ".cursor/mcp.json"
      },
      "http_jsonrpc": {
        "endpoint": "https://aipassport.cloud/mcp",
        "methods": [
          "initialize",
          "tools/list",
          "tools/call",
          "ping"
        ],
        "note": "JSON-RPC 2.0 \u0447\u0435\u0440\u0435\u0437 POST \u0441 Content-Type: application/json. \u041a\u043b\u0438\u0435\u043d\u0442 \u0434\u043e\u043b\u0436\u0435\u043d \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u0438\u0432\u0430\u0442\u044c \u044d\u0442\u043e\u0442 HTTP-\u0442\u0440\u0430\u043d\u0441\u043f\u043e\u0440\u0442; \u0434\u043b\u044f stdio \u043d\u0443\u0436\u0435\u043d \u043b\u043e\u043a\u0430\u043b\u044c\u043d\u044b\u0439 \u043c\u043e\u0441\u0442."
      },
      "no_mcp_fallback": {
        "directory": "https://aipassport.cloud/api/v1/directory",
        "llms_index": "https://aipassport.cloud/llms.txt",
        "location_offer_search": "https://aipassport.cloud/api/v1/locations/offers/search",
        "manifest": "https://aipassport.cloud/.well-known/aipassport.json",
        "note": "\u0415\u0441\u043b\u0438 MCP \u043d\u0435\u0434\u043e\u0441\u0442\u0443\u043f\u0435\u043d \u2014 REST \u0438 llms.txt/JSON-LD \u043e\u0441\u0442\u0430\u044e\u0442\u0441\u044f \u043a\u0430\u043d\u043e\u043d\u0438\u0447\u0435\u0441\u043a\u0438\u043c\u0438.",
        "offer_search": "https://aipassport.cloud/api/v1/offers/search",
        "search": "https://aipassport.cloud/api/v1/search"
      },
      "stdio_bridge": {
        "command": "python scripts/mcp_stdio_bridge.py",
        "cursor_config": {
          "mcpServers": {
            "aipassport": {
              "args": [
                "scripts/mcp_stdio_bridge.py"
              ],
              "command": "python",
              "env": {
                "AIPASSPORT_MCP_URL": "https://aipassport.cloud/mcp"
              }
            }
          }
        },
        "env": {
          "AIPASSPORT_MCP_URL": "https://aipassport.cloud/mcp"
        },
        "when": "\u041a\u043b\u0438\u0435\u043d\u0442 \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u0438\u0432\u0430\u0435\u0442 \u0442\u043e\u043b\u044c\u043a\u043e \u043b\u043e\u043a\u0430\u043b\u044c\u043d\u044b\u0439 stdio-\u043f\u0440\u043e\u0446\u0435\u0441\u0441, \u0431\u0435\u0437 URL."
      },
      "vscode_copilot": {
        "config": {
          "servers": {
            "aipassport": {
              "url": "https://aipassport.cloud/mcp"
            }
          }
        },
        "file": ".vscode/mcp.json"
      }
    },
    "endpoint": "https://aipassport.cloud/mcp",
    "protocol_version": "2024-11-05",
    "tools": [
      "search_businesses",
      "search_offers",
      "search_location_offers",
      "list_sectors",
      "list_cities",
      "list_countries",
      "get_passport"
    ],
    "transport": "http-jsonrpc"
  },
  "name": "AiPassport.cloud",
  "notes": [
    "MCP server at /mcp \u2014 JSON-RPC tools: search_businesses, search_offers, search_location_offers, list_sectors, list_cities, list_countries, get_passport.",
    "Examples are URL templates: replace brace placeholders with values from the dictionaries or search results; URL-encode free text.",
    "Public discovery, dictionaries and read-only search do not require an API key.",
    "Business and offer search responses contain results, count and next_cursor. Branch offer search contains results, count and coordinates_used.",
    "Primary path: open the passport human_view, JSON-LD, or per-entity llms.txt. These are canonical and sufficient for crawlers and AI assistants.",
    "API search is optional. Do not abandon a passport if API access is unsupported; use the canonical page, JSON-LD, and llms.txt instead.",
    "Public phone is omitted when owner has not granted phone_publish_consent.",
    "AiPassport is a seller-stated verified passport snapshot, not a live inventory system.",
    "Trust status and confirmed issues apply only to a concrete passport_id. Unverified user reports are private and do not automatically lower public trust.",
    "Avoid broad crawling when a canonical passport URL is known; prefer the passport page, JSON-LD, and llms.txt facts."
  ],
  "offer_search": {
    "active_only_default": true,
    "delivery": "city/country filter the physical business location. Shipping questions require an explicit delivery_target_country; optionally add delivery_target_city or delivery_target_region. Only items marked delivery_available=true qualify.",
    "dictionaries": "Use the country, city and sector dictionaries; send the customer\u0027s service or product question in query.",
    "example": "https://aipassport.cloud/api/v1/offers/search?country={country_code}\u0026city={city_id}\u0026query={url_encoded_question}\u0026sort=price_asc",
    "max_limit": 50,
    "method": "GET",
    "official_only_default": true,
    "optional": true,
    "pagination": "Repeat the request with ?cursor=\u003cnext_cursor\u003e from the previous response; null means no more results",
    "purpose": "Optional structured search for agents that already support API calls",
    "rate_limit": "30 requests/minute per IP",
    "required_filters": "At least one of: sector, city, country, query, tag, category",
    "sort": [
      "auto",
      "trust",
      "price_asc",
      "fresh"
    ],
    "sort_default": "auto: a cheaper-please wording in query sorts by price, otherwise trust"
  },
  "optional_request_headers": {
    "X-AiPassport-Agent": "Agent name for analytics (e.g. perplexity, yandex-browser-agent, openclaw)"
  },
  "publication_model": {
    "after_term_ends": "Keeps working normally for a 7-day renewal grace period. After that it leaves search, MCP results and the next sitemap snapshot; pages switch to noindex and stay at their address as an outdated snapshot with a freshness warning (no 404).",
    "automatic_renewal": false,
    "paid_term_days": 30,
    "purpose": "Each renewal is an explicit owner action, so the published set stays maintained instead of accumulating abandoned or auto-renewed listings.",
    "review_before_publication": true
  },
  "schema_version": "1.0",
  "search": {
    "dictionaries": "Use /api/v1/directory/sectors, /api/v1/directory/countries and /api/v1/directory/cities for exact filter values. Scope city names by country; prefer city IDs.",
    "example": "https://aipassport.cloud/api/v1/search?country={country_code}\u0026city={city_id}\u0026sector={sector_code}",
    "max_limit": 50,
    "method": "GET",
    "official_only": true,
    "online_projects": {
      "example": "https://aipassport.cloud/api/v1/search?city={city_id}\u0026format=online\u0026product=mobile_app",
      "filters": "format=online|standard; product=\u003ckind\u003e implies format=online",
      "meaning": "business_format=online marks an online project: website, app, online service, catalog, bot or platform. It has no storefront; city means the city it serves, not a visitor address.",
      "online_scope": "local (one city), nationwide (one country), global (worldwide)",
      "product_kinds": [
        "website",
        "catalog",
        "online_store",
        "marketplace",
        "web_service",
        "platform",
        "ai_agent",
        "mobile_app",
        "desktop_app",
        "game",
        "bot"
      ]
    },
    "optional": true,
    "pagination": "Repeat the request with ?cursor=\u003cnext_cursor\u003e from the previous response; null means no more results",
    "rate_limit": "30 requests/minute per IP",
    "required_filters": "At least one of: sector, city, country, tag, parent, format=online, product"
  },
  "search_architecture": [
    "Start with list_countries, list_cities and list_sectors to obtain exact filter values.",
    "Use search_businesses for companies, search_offers for products/services and search_location_offers for branch-specific prices and addresses. Corresponding REST endpoints are listed in this manifest.",
    "Read a known passport with get_passport or its canonical HTML, JSON-LD and llms.txt. Search is not necessary when its URL is already known.",
    "Search returns published owner-stated facts, not an external AI recommendation or confirmation of stock availability."
  ],
  "trust_response_headers": [
    "X-AiPassport-Passport-Id",
    "X-AiPassport-Verified",
    "X-AiPassport-Official",
    "X-AiPassport-Hash",
    "X-AiPassport-Readiness",
    "X-AiPassport-Subscription-Active"
  ],
  "trust_status_values": {
    "active": "Passport exists; snapshot may not have a validity date yet.",
    "confirmed_issues": "Confirmed trust issue or active suspension exists for this passport_id only.",
    "fresh_snapshot": "Publication is in its current paid term or 7-day renewal grace period. An old snapshot validity date does not override a renewed paid term.",
    "stale_snapshot": "No active paid term remains and the renewal grace period has ended; use caution."
  },
  "website_installation": {
    "api_key_required": false,
    "configuration": {
      "availability": "Missing, private, and unpublished passports return the same generic 404. Respect available_until and cache_seconds. Load script_url only when tag_active is true and tag_until has not expired; a paused tag does not by itself make the approved public passport unavailable.",
      "method": "GET",
      "response_fields": [
        "schema_version",
        "passport_id",
        "title",
        "passport_url",
        "json_url",
        "llms_url",
        "tag_active",
        "script_url",
        "tag_until",
        "available_until",
        "cache_seconds"
      ],
      "schema_version": 1,
      "url_template": "https://aipassport.cloud/api/v1/site-install/{passport_id}"
    },
    "crawler_note": "Follow the static JSON-LD and llms.txt alternate links without requiring JavaScript. Installation is not evidence that a named AI visited and does not guarantee indexing, ranking, or recommendations.",
    "default_display": "invisible",
    "guide_url": "https://aipassport.cloud/for-business#website-installation",
    "imports_or_syncs_cms": false,
    "optional": true,
    "optional_display": "compact passport button, not a full card or column",
    "other_websites": {
      "delivery": "html_code",
      "requires": "A platform that permits custom HEAD code and optional button HTML"
    },
    "read_only": true,
    "requires": "An existing publicly published passport",
    "tag_managers": {
      "crawler_note": "Tag-manager installation requires JavaScript. Static alternate links in HEAD remain useful for crawlers that do not execute scripts.",
      "delivery": "custom_html_script",
      "purpose": "Alternative delivery of the same AiPassport website tag; install it once. This does not replace or import Google/Yandex analytics counters.",
      "supported": [
        "Google Tag Manager",
        "Yandex.Metrica Tag Manager"
      ]
    },
    "tilda": {
      "delivery": "html_code",
      "plugin_required": false,
      "requires": "Paid custom HEAD setting and republished pages; optional button in T123"
    },
    "wordpress": {
      "delivery": "zip_plugin",
      "directory_listing": false,
      "download_url": "https://aipassport.cloud/api/v1/site-install/wordpress.zip",
      "requires": "Hosting or a WordPress.com plan that permits plugin uploads"
    }
  }
}