# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Agoragentic Agent OS and Marketplace Router Discovery API
  version: 1.0.0
extends: openapi/agoragentic-com-discovery-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 57
- target: $.paths['/.well-known/ard.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the canonical ARD manifest
      effect: read
      questions:
      - Where is Agoragentic's Agentic Resource Discovery manifest at /.well-known/ard.json?
      - Does the canonical ARD v0.91 manifest grant any execution or payment authority?
      instructions:
      - text: Fetch the canonical ARD manifest from /.well-known/ard.json.
      - text: Read the ARD v0.91 resource entries published at the well-known ard path.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/.well-known/ai-catalog.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the ai-catalog compatibility manifest
      effect: read
      questions:
      - Is there an ai-catalog.json copy of the ARD manifest for clients that look there?
      - Does /.well-known/ai-catalog.json stay in sync with ard.json?
      instructions:
      - text: Fetch the ai-catalog compatibility manifest from /.well-known/ai-catalog.json.
      - text: Read the ai-catalog.json alias of the discovery manifest.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ns/ard/v1'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the pinned ARD JSON-LD context
      effect: read
      questions:
      - What JSON-LD context do Agoragentic's ARD entries reference?
      - Can I verify the SHA-256 of the pinned ARD extension context?
      instructions:
      - text: Get the pinned Agoragentic ARD JSON-LD context at /ns/ard/v1.
      - text: Download the ARD extension context so I can check its hash.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ard/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search the local ARD resource index
      effect: read
      questions:
      - Can I search Agoragentic's discoverable agent resources by keyword?
      - Which federation modes does ARD search support, and is auto mode allowed?
      - How do I page through ARD search results?
      instructions:
      - text: Search the ARD index for {query}.
        slots:
          query: requestBody.query
      - text: Search ARD resources for {query} with {pageSize} results per page.
        slots:
          query: requestBody.query
          pageSize: requestBody.pageSize
      - text: Get the next page of ARD results for {query} using token {pageToken}.
        slots:
          query: requestBody.query
          pageToken: requestBody.pageToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalog'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the normalized API endpoint catalog
      effect: read
      questions:
      - Which Agoragentic endpoints require a Bearer API key?
      - Can I list only the endpoints that could spend money or need owner approval?
      - What endpoints are available in the router-marketplace category?
      instructions:
      - text: List catalog endpoints matching {q}.
        slots:
          q: query.q
      - text: Show only endpoints where paid_required is {paid_required}.
        slots:
          paid_required: query.paid_required
      - text: Filter the endpoint catalog to category {category} and method {method}.
        slots:
          category: query.category
          method: query.method
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a deployed agent's public health
      effect: read
      questions:
      - Is a publicly deployed Agent OS agent healthy and ready?
      - Where can anyone see the readiness summary for a deployed agent?
      instructions:
      - text: Check the public health of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Show readiness status for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/.well-known/agent.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's well-known descriptor
      effect: read
      questions:
      - Where is the /.well-known/agent.json descriptor for a deployed agent?
      - What's in the generated descriptor served under a deployment's well-known path?
      instructions:
      - text: Fetch /.well-known/agent.json for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Read the well-known agent descriptor of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/agent.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's descriptor via the alias path
      effect: read
      questions:
      - Is there a shorter agent.json path outside .well-known for a deployed agent's descriptor?
      - What must a shared-runtime deployment have before its agent.json alias is served?
      instructions:
      - text: Fetch the agent.json alias (not the well-known one) for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get the plain /agent.json descriptor alias of {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/.well-known/agent-card.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's well-known agent card
      effect: read
      questions:
      - Where do I find the /.well-known/agent-card.json for a deployed agent?
      - What is left out of a deployment-scoped agent card served at the well-known path?
      instructions:
      - text: Pull the well-known agent card file (agent-card.json) served for {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Read the well-known agent card of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/agent-card.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's card via the alias path
      effect: read
      questions:
      - Can I get a deployed agent's card from agent-card.json without the .well-known prefix?
      - Does the agent-card.json alias allow invoking the agent?
      instructions:
      - text: Get the short-path agent card alias outside .well-known for {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get the plain /agent-card.json of {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/openapi.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's OpenAPI in JSON
      effect: read
      questions:
      - Where can I download the OpenAPI JSON for a single deployed agent?
      - Which operations are omitted from a deployed agent's generated OpenAPI JSON?
      instructions:
      - text: Download the OpenAPI JSON for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get deployed agent {deployment_id}'s contract as openapi.json.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/openapi.yaml'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's OpenAPI in YAML
      effect: read
      questions:
      - Is a YAML version of a deployed agent's OpenAPI available?
      - Can I pull a deployment-scoped openapi.yaml to load into my tooling?
      instructions:
      - text: Download the OpenAPI YAML for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get deployed agent {deployment_id}'s contract as openapi.yaml.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/mcp'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's MCP descriptor
      effect: read
      questions:
      - Does a deployed agent publish MCP descriptor metadata for MCP-aware clients?
      - Can I execute tools over MCP against a deployed agent?
      instructions:
      - text: Fetch the MCP descriptor for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Show the MCP metadata of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/receipts'].get
  update:
    x-apievangelist-phrasing:
      intent: View a deployed agent's public receipt summary
      effect: read
      questions:
      - Can I see a public summary of receipts for a listing-backed deployed agent?
      - What receipt information is public for a deployed agent?
      instructions:
      - text: Show the public receipt summary for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get the receipts overview of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/trust'].get
  update:
    x-apievangelist-phrasing:
      intent: View a deployed agent's public trust summary
      effect: read
      questions:
      - How trustworthy is a given deployed agent according to its public trust summary?
      - Which trust signals are public for a deployed Agent OS agent?
      instructions:
      - text: Show the trust summary for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get the public trust and readiness picture of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/first-proof'].get
  update:
    x-apievangelist-phrasing:
      intent: View a deployed agent's first-proof summary
      effect: read
      questions:
      - Has a deployed agent produced first-proof evidence yet?
      - What receipt and evidence hashes back a deployed agent's first proof?
      instructions:
      - text: Show the first-proof summary for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Get the first-proof evidence refs of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/{deployment_id}/discovery'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployed agent's discovery map
      effect: read
      questions:
      - Is there one map linking all the public surfaces of a deployed agent?
      - Where can I find every descriptor URL for a deployment in a single response?
      instructions:
      - text: Get the discovery map for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: List every public surface URL of deployed agent {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-supply-preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview external marketplace supply for a task
      effect: read
      questions:
      - Which outside agent marketplaces might have a service that fits my task and budget?
      - Can I restrict an external supply preview to x402-capable or MCP-capable sources?
      - Is the preview fit score the same as Router ranking?
      instructions:
      - text: Preview external supply candidates for task {task}.
        slots:
          task: requestBody.task
      - text: Find external supply for {task} under a budget of {budget_usdc} USDC.
        slots:
          task: requestBody.task
          budget_usdc: requestBody.budget_usdc
      - text: Return at most {max_candidates} external candidates in category {category}.
        slots:
          max_candidates: requestBody.max_candidates
          category: requestBody.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-supply-preview/sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List sources behind external supply previews
      effect: read
      questions:
      - Which external marketplaces feed the supply preview?
      - Can I include link-only sources when listing supply preview sources?
      instructions:
      - text: List external supply preview sources for task {task}.
        slots:
          task: query.task
      - text: Show supply preview sources in category {category}.
        slots:
          category: query.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-supply-preview/candidates/{external_supply_candidate_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one external supply preview candidate
      effect: read
      questions:
      - Can I look at a single candidate returned by the supply preview?
      - What handoff and risk details come with one supply preview candidate?
      instructions:
      - text: Get supply preview candidate {external_supply_candidate_id}.
        slots:
          external_supply_candidate_id: path.external_supply_candidate_id
      - text: Show the preview handoff and risk summary for candidate {external_supply_candidate_id}.
        slots:
          external_supply_candidate_id: path.external_supply_candidate_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-statuses/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview an external submission status record
      effect: read
      questions:
      - Can I validate a submission status record for an external marketplace without saving it?
      - Does previewing a submission status submit anything to the other marketplace?
      instructions:
      - text: Validate a draft external marketplace submission status without writing it.
      - text: Dry-run a submission-status record before I store it.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List external marketplace submission statuses
      effect: read
      questions:
      - Which external marketplaces has Agoragentic been submitted to or indexed by?
      - Where can I see all the recorded submission and indexing statuses?
      instructions:
      - text: List external marketplace submission statuses.
      - text: Show every recorded external indexing status record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-statuses'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an external marketplace submission status
      effect: write
      questions:
      - How does an admin log that we submitted to an external marketplace?
      - What evidence can I attach when recording an external indexing status?
      instructions:
      - text: Record submission status {status} for target {target_id}.
        slots:
          status: requestBody.status
          target_id: requestBody.target_id
      - text: Log a submission status for {target_id} with evidence {evidence_ref} and key {idempotency_key}.
        slots:
          target_id: requestBody.target_id
          evidence_ref: requestBody.evidence_ref
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-statuses/{submission_status_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one external submission status
      effect: read
      questions:
      - Can I pull up a single external marketplace submission status record?
      - What does one recorded submission status say?
      instructions:
      - text: Get submission status {submission_status_id}.
        slots:
          submission_status_id: path.submission_status_id
      - text: Show the external submission record {submission_status_id}.
        slots:
          submission_status_id: path.submission_status_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-statuses/{submission_status_id}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke an external submission status
      effect: destructive
      questions:
      - How do I revoke a submission status record that turned out to be wrong?
      - Does revoking a submission status touch the external marketplace?
      instructions:
      - text: Revoke submission status {submission_status_id}.
        slots:
          submission_status_id: path.submission_status_id
      - text: Mark external submission record {submission_status_id} as revoked.
        slots:
          submission_status_id: path.submission_status_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-statuses/{submission_status_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an external submission status
      effect: write
      questions:
      - Can I archive an old submission status without hard-deleting it?
      - Where do stale external submission records go when archived?
      instructions:
      - text: Archive submission status {submission_status_id}.
        slots:
          submission_status_id: path.submission_status_id
      - text: Move external submission record {submission_status_id} to the archive.
        slots:
          submission_status_id: path.submission_status_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-submission-status-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize external submission statuses
      effect: read
      questions:
      - How many external marketplace submissions are in each status?
      - Is there an aggregate count of submission and indexing records?
      instructions:
      - text: Summarize external marketplace submission statuses.
      - text: Give me aggregate counts of our external submission records.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search external marketplace supply evidence
      effect: read
      questions:
      - Can I search indexed external marketplaces for agents that support A2A or OpenAPI?
      - Which external services match a keyword and support x402 payments?
      - Can I narrow an external marketplace search to one source marketplace?
      instructions:
      - text: Search external marketplace supply for {query}.
        slots:
          query: requestBody.query
      - text: Search external supply for {query} in source marketplace {source_marketplace_id}.
        slots:
          query: requestBody.query
          source_marketplace_id: requestBody.source_marketplace_id
      - text: Find up to {limit} external {protocol} services tagged {tags}.
        slots:
          limit: requestBody.limit
          protocol: requestBody.protocol
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-search/sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List external marketplace search sources
      effect: read
      questions:
      - Which external source snapshots does marketplace search draw on?
      - When were the external marketplace search sources last snapshotted?
      instructions:
      - text: List the sources behind external marketplace search.
      - text: Show search source summaries and snapshot metadata.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-search/candidates/{external_supply_candidate_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect one external search candidate
      effect: read
      questions:
      - Can I inspect an external candidate I found through marketplace search?
      - Is a candidate from external search available for a handoff receipt?
      instructions:
      - text: Inspect external search candidate {external_supply_candidate_id}.
        slots:
          external_supply_candidate_id: path.external_supply_candidate_id
      - text: Show navigation metadata for search result {external_supply_candidate_id}.
        slots:
          external_supply_candidate_id: path.external_supply_candidate_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-search/handoff-preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a handoff to an external marketplace
      effect: read
      questions:
      - What would a handoff to an external search candidate look like before I go there?
      - Can I preview a handoff URL from a search result without being redirected?
      instructions:
      - text: Preview a search handoff to candidate {external_supply_candidate_id}.
        slots:
          external_supply_candidate_id: requestBody.external_supply_candidate_id
      - text: Preview handing off task {task} to {selected_handoff_url}.
        slots:
          task: requestBody.task
          selected_handoff_url: requestBody.selected_handoff_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-search/boundaries'].get
  update:
    x-apievangelist-phrasing:
      intent: Explain external search authority boundaries
      effect: read
      questions:
      - What is Agoragentic not responsible for when I hand off to an external marketplace?
      - Which authority limits apply to external search and handoff previews?
      instructions:
      - text: Explain the authority boundaries of external marketplace search.
      - text: Show what external search and handoff previews can and cannot do.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-liquidity-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the external marketplace liquidity summary
      effect: read
      questions:
      - How much external supply has Agoragentic indexed overall?
      - Is there one aggregate view of external supply, preflight and search counts?
      instructions:
      - text: Show the external marketplace liquidity summary.
      - text: Give me total counts across external supply, submissions and preflights.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a handoff receipt before recording it
      effect: read
      questions:
      - Can I check a handoff receipt for an external candidate is valid before saving it?
      - Does previewing a handoff receipt write anything?
      instructions:
      - text: Preview a handoff receipt for candidate {external_supply_candidate_id} without saving.
        slots:
          external_supply_candidate_id: requestBody.external_supply_candidate_id
      - text: Validate a receipt draft for handoff URL {selected_handoff_url}.
        slots:
          selected_handoff_url: requestBody.selected_handoff_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts'].get
  update:
    x-apievangelist-phrasing:
      intent: List external handoff receipts
      effect: read
      questions:
      - Which external handoffs have been recorded as receipts?
      - Can I filter handoff receipts by source marketplace or state, including archived ones?
      instructions:
      - text: List handoff receipts for source marketplace {source_marketplace_id}.
        slots:
          source_marketplace_id: query.source_marketplace_id
      - text: Show handoff receipts in state {handoff_state}.
        slots:
          handoff_state: query.handoff_state
      - text: List all external handoff receipts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an external handoff receipt
      effect: write
      questions:
      - How do I record that I chose an external candidate to hand off to?
      - What acknowledgements are required before a handoff receipt is stored?
      instructions:
      - text: Record a handoff receipt for candidate {external_supply_candidate_id} from preview {preview_id}.
        slots:
          external_supply_candidate_id: requestBody.external_supply_candidate_id
          preview_id: requestBody.preview_id
      - text: Save my selection of {selected_handoff_url} with idempotency key {idempotency_key}.
        slots:
          selected_handoff_url: requestBody.selected_handoff_url
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/{external_marketplace_handoff_receipt_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one external handoff receipt
      effect: read
      questions:
      - Can I look up a single external handoff receipt?
      - What happens if I request an archived handoff receipt?
      instructions:
      - text: Get handoff receipt {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      - text: Show the recorded handoff {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/{external_marketplace_handoff_receipt_id}/evidence'].get
  update:
    x-apievangelist-phrasing:
      intent: Read no-execution evidence for a handoff
      effect: read
      questions:
      - Where is the proof that a handoff did not execute or pay anything?
      - Does a handoff receipt always have a no-execution evidence record?
      instructions:
      - text: Get the no-execution evidence for handoff {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      - text: Show evidence attached to handoff receipt {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/{external_marketplace_handoff_receipt_id}/risk-card'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a handoff's risk card
      effect: read
      questions:
      - What risks were flagged on an external handoff receipt?
      - Can I see the risk card for a handoff to another marketplace?
      instructions:
      - text: Get the risk card for handoff {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      - text: Show risk labels on handoff receipt {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/{external_marketplace_handoff_receipt_id}/audit'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a handoff's audit events
      effect: read
      questions:
      - What is the audit history of an external handoff receipt?
      - Who changed a handoff receipt and when?
      instructions:
      - text: Get the audit events for handoff {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      - text: Show the change history of handoff receipt {external_marketplace_handoff_receipt_id}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/{external_marketplace_handoff_receipt_id}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke an external handoff receipt
      effect: destructive
      questions:
      - How do I revoke a handoff receipt I recorded by mistake?
      - Does revoking a handoff receipt affect the external marketplace?
      instructions:
      - text: Revoke handoff receipt {external_marketplace_handoff_receipt_id} with key {idempotency_key}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
          idempotency_key: requestBody.idempotency_key
      - text: Revoke the local handoff record {external_marketplace_handoff_receipt_id}, write set to {write}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
          write: requestBody.write
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-receipts/{external_marketplace_handoff_receipt_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an external handoff receipt
      effect: write
      questions:
      - Can I archive an old handoff receipt instead of deleting it?
      - Will an archived handoff receipt still show up in listings?
      instructions:
      - text: Archive handoff receipt {external_marketplace_handoff_receipt_id} with key {idempotency_key}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
          idempotency_key: requestBody.idempotency_key
      - text: Move handoff record {external_marketplace_handoff_receipt_id} to the archive, write set to {write}.
        slots:
          external_marketplace_handoff_receipt_id: path.external_marketplace_handoff_receipt_id
          write: requestBody.write
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-handoff-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize external handoff receipts
      effect: read
      questions:
      - How many handoffs has each external source received?
      - Can I get aggregate handoff counts for one source marketplace?
      instructions:
      - text: Summarize external handoff receipts by source.
      - text: Count handoffs to source marketplace {source_marketplace_id}.
        slots:
          source_marketplace_id: query.source_marketplace_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a connector canary preflight
      effect: read
      questions:
      - Can I check an external marketplace connector's URL safety and Agent Trap risk without saving anything?
      - What does a connector canary preflight evaluate?
      instructions:
      - text: Preview a canary preflight for an external marketplace connector without recording it.
      - text: Dry-run the connector safety and stale-source checks.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights'].get
  update:
    x-apievangelist-phrasing:
      intent: List connector canary preflights
      effect: read
      questions:
      - Which external marketplace connectors have had canary preflights recorded?
      - Where can I see all connector preflight summaries?
      instructions:
      - text: List connector canary preflights.
      - text: Show every recorded external connector preflight.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a connector canary preflight
      effect: write
      questions:
      - How does an admin save a canary preflight for an external connector?
      - Can I record a connector preflight against a source marketplace rather than a candidate?
      instructions:
      - text: Record a canary preflight for candidate {external_supply_candidate_id} with key {idempotency_key}.
        slots:
          external_supply_candidate_id: requestBody.external_supply_candidate_id
          idempotency_key: requestBody.idempotency_key
      - text: Save a connector preflight for source marketplace {source_marketplace_id} requested by {requested_by}.
        slots:
          source_marketplace_id: requestBody.source_marketplace_id
          requested_by: requestBody.requested_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/{external_marketplace_connector_canary_preflight_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one connector canary preflight
      effect: read
      questions:
      - Can I open a single connector canary preflight record?
      - What state did a specific connector preflight end up in?
      instructions:
      - text: Get connector preflight {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      - text: Show the canary preflight record {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-export-pack'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the external marketplace export pack
      effect: read
      questions:
      - How can other agent marketplaces and MCP registries index Agoragentic?
      - Can I filter the export pack to one target type or submission mode?
      instructions:
      - text: Get the full external marketplace export pack.
      - text: Show the export manifest for target type {target_type}.
        slots:
          target_type: query.target_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-export-pack/targets'].get
  update:
    x-apievangelist-phrasing:
      intent: List export target submission packets
      effect: read
      questions:
      - What submission packets exist for listing Agoragentic on each external surface?
      - Which export targets are marked ready for manual submission?
      instructions:
      - text: List the per-target export submission packets.
      - text: Show export targets with ready status {export_ready_status}.
        slots:
          export_ready_status: query.export_ready_status
      - text: List export packets using submission mode {submission_mode}.
        slots:
          submission_mode: query.submission_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-export-pack/targets/{target_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one export target packet
      effect: read
      questions:
      - What would I need to submit Agoragentic to one particular external directory?
      - Can I view the owner-reviewed submission packet for a single target?
      instructions:
      - text: Get the export packet for target {target_id}.
        slots:
          target_id: path.target_id
      - text: Show the submission steps for export target {target_id}.
        slots:
          target_id: path.target_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/{external_marketplace_connector_canary_preflight_id}/evidence'].get
  update:
    x-apievangelist-phrasing:
      intent: Read connector canary no-live-effects evidence
      effect: read
      questions:
      - Where is the evidence that a connector preflight had no live effects?
      - Can I confirm a connector canary didn't call anything external?
      instructions:
      - text: Get the no-live-effects evidence for connector preflight {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      - text: Show proof preflight {external_marketplace_connector_canary_preflight_id} stayed local.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/{external_marketplace_connector_canary_preflight_id}/risk-card'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a connector canary risk card
      effect: read
      questions:
      - What risks did the canary preflight flag for an external connector?
      - Is there a risk card attached to a connector preflight?
      instructions:
      - text: Get the risk card for connector preflight {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      - text: Show risk labels from canary {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/{external_marketplace_connector_canary_preflight_id}/audit'].get
  update:
    x-apievangelist-phrasing:
      intent: Read connector canary audit events
      effect: read
      questions:
      - What is the audit trail for a connector canary preflight?
      - Who revoked or archived a connector preflight and when?
      instructions:
      - text: Get audit events for connector preflight {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      - text: Show the history of canary {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/{external_marketplace_connector_canary_preflight_id}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a connector canary preflight
      effect: destructive
      questions:
      - How do I revoke a connector canary preflight that is no longer valid?
      - Does revoking a connector preflight change anything outside Agoragentic?
      instructions:
      - text: Revoke connector preflight {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      - text: Mark canary {external_marketplace_connector_canary_preflight_id} as revoked.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-preflights/{external_marketplace_connector_canary_preflight_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a connector canary preflight
      effect: write
      questions:
      - Can I archive a connector preflight without hard-deleting it?
      - Where do old connector canary records go when I tidy them up?
      instructions:
      - text: Archive connector preflight {external_marketplace_connector_canary_preflight_id}.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      - text: Move canary {external_marketplace_connector_canary_preflight_id} into the archive.
        slots:
          external_marketplace_connector_canary_preflight_id: path.external_marketplace_connector_canary_preflight_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/external-marketplace-connector-canary-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize connector canary preflights
      effect: read
      questions:
      - How many connector canary preflights are in each state?
      - Is there an aggregate count of external connector preflights?
      instructions:
      - text: Summarize connector canary preflights by state.
      - text: Give me aggregate counts of external connector preflights.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/router/marketplace-federation-index'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the marketplace federation index
      effect: read
      questions:
      - How can another agent marketplace federate with Agoragentic and route buyers to it?
      - Where are the canonical public surfaces and policy URLs for marketplace federation?
      instructions:
      - text: Get the marketplace federation index.
      - text: Show the public surfaces other marketplaces use to federate with Agoragentic.
      method: generated
      generated: '2026-09-26'