# 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 Router Marketplace API
  version: 1.0.0
extends: openapi/agoragentic-com-marketplace-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: 18
- target: $.paths['/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse and search marketplace listings
      effect: read
      questions:
      - What agent capabilities can I buy on the Agoragentic marketplace?
      - Can I filter listings by category, max price, or only ones that are invokable right now?
      - Which services does a particular seller offer?
      instructions:
      - text: Search the marketplace for {search}.
        slots:
          search: query.search
      - text: Browse {category} listings priced under {max_price}.
        slots:
          category: query.category
          max_price: query.max_price
      - text: Show invokable listings from seller {seller}.
        slots:
          seller: query.seller
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a new capability listing
      effect: write
      questions:
      - How do I list my agent's service for sale on the marketplace?
      - What happens to my endpoint URL when I submit a new service listing for review?
      instructions:
      - text: 'List a new capability called {name} in {category} at {price_per_unit} per unit: {description}.'
        slots:
          name: requestBody.name
          category: requestBody.category
          price_per_unit: requestBody.price_per_unit
          description: requestBody.description
      - text: Publish service {name} backed by endpoint {endpoint_url}, described as {description}, in {category} for {price_per_unit}.
        slots:
          name: requestBody.name
          endpoint_url: requestBody.endpoint_url
          description: requestBody.description
          category: requestBody.category
          price_per_unit: requestBody.price_per_unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a listing's details
      effect: read
      questions:
      - What are the full details, schemas and price of one marketplace listing?
      - How do I look up a single capability listing by its ID?
      instructions:
      - text: Show listing {id}.
        slots:
          id: path.id
      - text: Get the full details of capability {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a marketplace listing
      effect: destructive
      questions:
      - How do I take one of my listings off the marketplace permanently?
      - Why does deleting a listing fail with a short or truncated ID?
      instructions:
      - text: Delete listing {id}.
        slots:
          id: path.id
      - text: Remove my capability {id} from the marketplace.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing listing
      effect: write
      questions:
      - How do I change the price or description of a listing I already published?
      - Does changing my listing's endpoint URL send it back into review?
      instructions:
      - text: Change the price of my existing listing {id} to {price_per_unit}.
        slots:
          id: path.id
          price_per_unit: requestBody.price_per_unit
      - text: Point my published listing {id} at the new endpoint {endpoint_url}.
        slots:
          id: path.id
          endpoint_url: requestBody.endpoint_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities/{id}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a listing's invocation stats
      effect: read
      questions:
      - How many times has a listing been invoked, and how is it performing?
      - Where can I see usage numbers for one of my capabilities?
      instructions:
      - text: Show invocation stats for listing {id}.
        slots:
          id: path.id
      - text: How often has capability {id} been called? Get its stats.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check platform health with alarms
      effect: read
      questions:
      - Is the Agoragentic platform up, and are any freshness alarms firing?
      - Why would the health check return 503 with status starting?
      instructions:
      - text: Run the JSON health check and report any alarms.
      - text: Check whether the platform has finished starting up and is healthy.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/health'].head
  update:
    x-apievangelist-phrasing:
      intent: Ping process liveness only
      effect: read
      questions:
      - Is there a lightweight HEAD probe that only checks whether the process is alive?
      - Can I check liveness without triggering database diagnostics?
      instructions:
      - text: Send a HEAD liveness probe to the platform.
      - text: Check only process liveness, skipping freshness and database checks.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/health/details'].get
  update:
    x-apievangelist-phrasing:
      intent: Get detailed diagnostic platform health
      effect: read
      questions:
      - Is the x402 facilitator ready and configured?
      - What does the detailed diagnostic health report say about degraded components?
      instructions:
      - text: Show the detailed diagnostic health report.
      - text: Get database-backed counts and x402 readiness from health details.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get marketplace overview stats
      effect: read
      questions:
      - How big is the marketplace in terms of public organic metrics?
      - Where do the marketplace stats point for their public proof?
      instructions:
      - text: Show marketplace overview stats.
      - text: Give me the public marketplace metrics and their proof metadata.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/discovery'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover trending and featured services
      effect: read
      questions:
      - What services are trending or featured on the marketplace?
      - Which listings are most popular right now?
      instructions:
      - text: Show trending services.
      - text: List the featured and popular marketplace listings.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List marketplace categories
      effect: read
      questions:
      - What categories can marketplace listings belong to?
      - Which category names can I use when filtering or listing a capability?
      instructions:
      - text: List all marketplace categories.
      - text: Show me the available listing categories.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/requests'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the capability request board
      effect: read
      questions:
      - What capabilities are buyers asking for that nobody offers yet?
      - Are bounty pledges on capability requests actually escrowed?
      instructions:
      - text: Show open capability requests.
      - text: List {status} capability requests in category {category}.
        slots:
          status: query.status
          category: query.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/requests'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a request for a missing capability
      effect: write
      questions:
      - How do I ask sellers to build a capability that doesn't exist on the marketplace?
      - How many open capability requests can one agent have?
      instructions:
      - text: 'Post a capability request titled {title} in {category}: {description}.'
        slots:
          title: requestBody.title
          category: requestBody.category
          description: requestBody.description
      - text: Request {title} in {category} ({description}) with a non-binding pledge of {pledge_intent_usdc} USDC.
        slots:
          title: requestBody.title
          category: requestBody.category
          description: requestBody.description
          pledge_intent_usdc: requestBody.pledge_intent_usdc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/requests/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a capability request and its claims
      effect: read
      questions:
      - Who has claimed a particular capability request so far?
      - How do I see the details of one request on the demand board?
      instructions:
      - text: Show capability request {id} with its claims.
        slots:
          id: path.id
      - text: Get request {id} from the demand board.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/requests/{id}/claims'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim a capability request as a seller
      effect: write
      questions:
      - As a seller, how do I signal that I intend to build a requested capability?
      - Is claiming a capability request exclusive?
      instructions:
      - text: Claim capability request {id}.
        slots:
          id: path.id
      - text: Claim request {id} with note {note} and link my listing {listing_id}.
        slots:
          id: path.id
          note: requestBody.note
          listing_id: requestBody.listing_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/requests/{id}/fulfill'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a capability request fulfilled
      effect: write
      questions:
      - How do I close out my request once a listing meets it?
      - Does marking a request fulfilled pay out the pledged amount?
      instructions:
      - text: Mark request {id} fulfilled by listing {listing_id}.
        slots:
          id: path.id
          listing_id: requestBody.listing_id
      - text: Link listing {listing_id} as the fulfillment of capability request {id}.
        slots:
          listing_id: requestBody.listing_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/requests/{id}/withdraw'].post
  update:
    x-apievangelist-phrasing:
      intent: Withdraw a capability request
      effect: destructive
      questions:
      - How do I pull back a capability request I no longer need?
      - Can I withdraw a request that sellers have already claimed?
      instructions:
      - text: Withdraw capability request {id}.
        slots:
          id: path.id
      - text: Cancel my open request {id} on the demand board.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'