# 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 Invoke API
  version: 1.0.0
extends: openapi/agoragentic-com-invoke-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: 5
- target: $.paths['/execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Route a task to the best provider and run it
      effect: write
      questions:
      - How do I hand a task to the router and let it pick a provider to run it?
      - Can I execute against a quote I already received instead of describing the task again?
      - What constraints can I pass when the router executes my task?
      instructions:
      - text: Route and execute the task {task} with input {input}.
        slots:
          task: requestBody.task
          input: requestBody.input
      - text: Execute quote {quote_id} through the router.
        slots:
          quote_id: requestBody.quote_id
      - text: Run task {task} under the constraints {constraints}.
        slots:
          task: requestBody.task
          constraints: requestBody.constraints
      method: generated
      generated: '2026-09-26'
- target: $.paths['/execute/match'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview which providers would take a task
      effect: read
      questions:
      - Which providers would the router consider for my task before I run it?
      - Can I cap price and latency when previewing matching providers?
      - Does the provider match preview include external candidates?
      instructions:
      - text: Preview the providers that match the task {task}.
        slots:
          task: query.task
      - text: Show matching providers for {task} costing at most {max_cost}.
        slots:
          task: query.task
          max_cost: query.max_cost
      - text: Preview matches for {task} in category {preferred_category} under {max_latency_ms} ms.
        slots:
          task: query.task
          preferred_category: query.preferred_category
          max_latency_ms: query.max_latency_ms
      method: generated
      generated: '2026-09-26'
- target: $.paths['/execute/status/{invocation_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a routed execution
      effect: read
      questions:
      - Did my router-executed task finish, and what does its receipt say?
      - What's the settlement status of a task the router ran for me?
      instructions:
      - text: Check the router execution status for invocation {invocation_id}.
        slots:
          invocation_id: path.invocation_id
      - text: Get the execution receipt and settlement state of routed call {invocation_id}.
        slots:
          invocation_id: path.invocation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoke/{capability_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Invoke a specific capability directly
      effect: write
      questions:
      - How do I call one particular capability without going through the router?
      - Can I invoke a capability asynchronously or pin a specific version?
      instructions:
      - text: Invoke capability {capability_id} with input {input}.
        slots:
          capability_id: path.capability_id
          input: requestBody.input
      - text: Call capability {capability_id} version {version} asynchronously.
        slots:
          capability_id: path.capability_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoke/{invocation_id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a direct invocation
      effect: read
      questions:
      - Has my direct capability invocation completed yet?
      - Where do I poll an async capability call I made directly?
      instructions:
      - text: Check the status of direct invocation {invocation_id}.
        slots:
          invocation_id: path.invocation_id
      - text: Poll my async capability call {invocation_id}.
        slots:
          invocation_id: path.invocation_id
      method: generated
      generated: '2026-09-26'