{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentSearch Search + Read",
    "version": "0.2.0",
    "description": "Search and read in one paid call: runs a live web search and returns the top 1-5 results with clean, LLM-ready markdown of each page (title, URL, snippet, score, page text), for grounding answers and RAG without separate search and extract calls. $0.015 USDC per call on Base; charged only when at least one page has text.",
    "contact": {
      "url": "https://agentsearchhq.com"
    }
  },
  "servers": [
    {
      "url": "https://api.agentsearchhq.com"
    }
  ],
  "paths": {
    "/x402/v1/search_and_read": {
      "post": {
        "operationId": "search_and_read",
        "summary": "Search and read in one paid call: runs a live web search and returns the top 1-5 results with clean, LLM-ready markdown of each page (title, URL, snippet, score, page text), for grounding answers and RAG without separate search and extract calls",
        "description": "Search and read in one paid call: runs a live web search and returns the top 1-5 results with clean, LLM-ready markdown of each page (title, URL, snippet, score, page text), for grounding answers and RAG without separate search and extract calls. $0.015 USDC per call on Base; charged only when at least one page has text.",
        "tags": [
          "search_and_read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 400,
                    "description": "Search query in natural language or keywords."
                  },
                  "num_results": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "default": 3,
                    "description": "How many top results to read (1-5)."
                  },
                  "max_results": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "description": "Alias of num_results (used only when num_results is absent)."
                  },
                  "max_chars": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20000,
                    "default": 8000,
                    "description": "Maximum markdown characters per page (1-20000)."
                  },
                  "render_fallback": {
                    "type": "boolean",
                    "default": false,
                    "description": "Retry at most one empty or thin page in a headless browser."
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              },
              "example": {
                "query": "latest x402 protocol news",
                "num_results": 3
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "Invalid JSON or input (never charged)"
          },
          "402": {
            "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header",
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "base64 JSON x402 v2 PaymentRequired"
              }
            }
          },
          "409": {
            "description": "Payment authorization already used"
          },
          "413": {
            "description": "Body too large"
          },
          "429": {
            "description": "Rate limited"
          },
          "502": {
            "description": "Upstream or facilitator failure (never charged)"
          },
          "503": {
            "description": "Service disabled or busy"
          },
          "200": {
            "description": "Result (payment settled; PAYMENT-RESPONSE header carries the receipt)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "result_count": {
                      "type": "integer"
                    },
                    "extracted_count": {
                      "type": "integer"
                    },
                    "retrieved_at": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          },
                          "score": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "domain": {
                            "type": "string"
                          },
                          "published_date": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "markdown": {
                            "type": "string"
                          },
                          "chars": {
                            "type": "integer"
                          },
                          "truncated": {
                            "type": "boolean"
                          },
                          "extract_status": {
                            "type": "string",
                            "enum": [
                              "ok",
                              "empty",
                              "failed",
                              "timeout",
                              "blocked",
                              "rendered"
                            ]
                          },
                          "source": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "results"
                  ]
                },
                "example": {
                  "query": "latest x402 protocol news",
                  "result_count": 1,
                  "extracted_count": 1,
                  "retrieved_at": "2026-11-10T12:00:00Z",
                  "results": [
                    {
                      "title": "x402 - payments protocol for the internet",
                      "url": "https://www.x402.org/",
                      "snippet": "x402 is an open payment standard built on HTTP 402 ...",
                      "score": 0.91,
                      "domain": "x402.org",
                      "published_date": null,
                      "markdown": "# x402\n\nx402 is an open payment standard ...",
                      "chars": 4120,
                      "truncated": false,
                      "extract_status": "ok",
                      "source": "extract"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.015"
          },
          "protocols": [
            {
              "x402": {
                "version": 2,
                "scheme": "exact",
                "network": "eip155:8453",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0xC49B157887e51c21CB655f39CF65D6a4c2a4C337"
              }
            }
          ]
        }
      }
    }
  },
  "externalDocs": {
    "url": "https://agentsearchhq.com/docs/x402#search-and-read",
    "description": "Direct x402 docs, Search + Read section"
  }
}