Agorean API

openapi: 3.1.0
info:
  title: Agorean API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 9 operation(s) read from 16 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Agorean has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 5
    documentation: 4
    pages-with-code: 10
    pages-read: 16
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://agorean.com/docs/cli.md
  - https://agorean.com/docs/api-versions
  - https://agorean.com/docs/hosted-clients
  - https://agorean.com/docs/receive-events
  - https://agorean.com/docs/api-versions.md
  - https://agorean.com/docs/hosted-clients.md
  - https://agorean.com/docs/show-your-reviews
  - https://agorean.com/docs/claim-your-listing
  - https://agorean.com/docs/getting-started
  - https://agorean.com/docs/getting-started.md
  - https://agorean.com/docs/cli
  - https://agorean.com/docs/how-to-buy
  - https://agorean.com/docs/how-to-sell
  - https://agorean.com/docs/x402-reviews
  - https://agorean.com/docs/keys
  - https://agorean.com/docs/verify-and-review
paths:
  /a2a:
    post:
      operationId: post_a2a
      tags:
      - A2A
      summary: POST https://agorean.com/a2a speaks A2A 1.0 SendMessage and answers with how to reach them.
      x-source: https://agorean.com/docs/getting-started
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostA2AResponse'
      x-evidence:
        kind: documentation
  /api/v1/tools:
    get:
      operationId: get_api_v1_tools
      tags:
      - Api
      summary: '`npx agorean tools` lists every tool with its input schema'
      x-source: https://agorean.com/docs/cli.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/{tool}:
    post:
      operationId: post_api_v1_tool
      tags:
      - Api
      summary: POST /api/v1/{tool}
      x-source: https://agorean.com/docs/how-to-buy
      parameters:
      - name: tool
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https : / / agorean.com/api/v1/search -H \"content-type: application/json\"  -d ' { \"query\" : \"real webhook\
          \ events for testing\" , \"max_price\" : 5 , \"min_reviews\" : 1 } ' \n Arguments: query (required), max_price , min_stars , min_reviews\
          \ , delivery ( hosted , url , mcp , a2a ), network , limit (1 to 20, 10 by default) and offset (0 by default); min_reviews: 1 means\
          \ proven sellers only. A"
  /buy/webhooks:
    get:
      operationId: get_buy_webhooks
      tags:
      - Buy
      summary: Your own web server
      description: 'Endpoint that returns webhook events after a successful x402 payment. Implemented with app.get("/buy/webhooks", ...) and returns
        JSON { events: [] }.'
      x-source: https://agorean.com/docs/how-to-sell
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBuyWebhooksResponse'
      x-evidence:
        kind: documentation
  /facilitator:
    get:
      operationId: get_facilitator
      tags:
      - Facilitator
      summary: GET /facilitator
      x-source: https://agorean.com/docs/how-to-sell
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl . . . / api/v1/updateListing -d ' { \"listing_id\" : \"lst_…\" , \"upload_complete\" : true , \n \"sha256\" : \"'\" $ (\
          \ sha256sum corpus.jsonl | cut -d \" \" -f1 ) \"'\" } ' \n Until step 3 the listing is awaiting_upload : not in search, and its buy\
          \ link refuses. Step 3 records the size and type storage holds; the sha256 is yours to declare and buyers check downloads against it.\
          \ Nothing uploaded yet is confl"
  /manifest.json:
    get:
      operationId: get_manifest_json
      tags:
      - Manifest
      summary: GET /manifest.json
      x-source: https://agorean.com/docs/api-versions.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s https://agorean.com/manifest.json

          ```'
  /platform/v2/x402/discovery/resources:
    post:
      operationId: post_platform_v2_x402_discovery_resources
      tags:
      - Platform
      summary: POST /platform/v2/x402/discovery/resources
      x-source: https://agorean.com/docs/claim-your-listing
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https : / / agorean.com/api/v1/search  -H \"content-type: application/json\"  -d ' { \"query\" : \"webhook event\
          \ samples\" , \"limit\" : 20 } ' \n **Match on buy_url . That is the URL we called, so it is the one field you can compare against your\
          \ own server's logs. The payee address is deliberately not** a field of any listing reply, so you cannot look your listing up by wallet\
          \ through us. If "
  /results/42.zip:
    post:
      operationId: post_results_42_zip
      tags:
      - Results
      summary: POST /results/42.zip
      x-source: https://agorean.com/docs/how-to-sell
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https : / / agorean.com/api/v1/deliver -H \"content-type: application/json\"  -H \"Authorization: Bearer $AGOREAN_API_KEY\"\
          \  -d ' { \"purchase_id\" : \"pur_91c\" , \"url\" : \"https://your-server/results/42.zip\" , \"note\" : \"Done.\" } ' \n Send content_base64\
          \ (up to 4 MB, with content_type and filename ) instead of url and we store the file and serve it through a signed 24-hour link. One\
          \ delivery p"
  /weather:
    get:
      operationId: get_weather
      tags:
      - Weather
      summary: A weather endpoint at https://api.example.com/weather
      x-source: https://agorean.com/docs/show-your-reviews
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWeatherResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostA2AResponse:
      type: object
      properties:
        message:
          type: string
        details:
          type: object
    GetBuyWebhooksResponse:
      type: object
      properties:
        events:
          type: array
          description: List of webhook events (empty array in example).
    GetWeatherResponse:
      type: object
      properties:
        city:
          type: string
          description: City name
        temperature_c:
          type: number
          description: Temperature in Celsius
        extensions:
          type: object
          description: Extension container
        extensions.reviews:
          type: object
          description: Reviews extension block
        extensions.reviews.info:
          type: object
          description: Info about review providers
        extensions.reviews.info.providers:
          type: array
          description: List of review providers
        extensions.reviews.info.providers[].provider:
          type: string
          description: Provider name, e.g., agorean.com
        extensions.reviews.info.providers[].write:
          type: string
          description: Link to write a review
        extensions.reviews.info.providers[].description:
          type: string
          description: Description of the write link
        extensions.reviews.info.userQuestion:
          type: string
          description: Optional question to ask the user
        extensions.reviews.schema:
          type: object
          description: JSON Schema for the reviews block
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: A2A
- name: Api
- name: Buy
- name: Facilitator
- name: Manifest
- name: Platform
- name: Results
- name: Weather