{"openapi": "3.0.3", "info": {"title": "Waltsoft SearchPulse AI Web Search with Grounded Answers", "description": "Real-time AI-powered web search with grounded, citation-backed answers. Submit a natural language query and receive a synthesized answer with source citations, token usage, and cost metadata. Designed for AI agents and automated research pipelines that need factual, up-to-date answers without hallucination. Standard queries are priced at $0.25 per call; deep research queries at $0.40 per call.\n", "version": "1.0.0"}, "servers": [{"url": "https://searchpulse.waltsoft.net/v1", "description": "SearchPulse production endpoint"}], "paths": {"/search": {"post": {"summary": "Submit a natural language search query", "description": "Submits a natural language query to the SearchPulse engine. Returns a synthesized, grounded answer with citations from live web sources along with token usage and cost metadata. Use mode=standard for quick lookups ($0.25/call) and mode=deep for comprehensive multi-source research ($0.40/call).\n", "operationId": "search", "tags": ["Search"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["query"], "properties": {"query": {"type": "string", "description": "Natural language search query", "example": "What are the current AWS EC2 instance types with the best price-to-performance ratio?"}, "mode": {"type": "string", "description": "Search depth. standard returns a fast single-pass answer ($0.25/call). deep performs multi-source synthesis for comprehensive research ($0.40/call).\n", "enum": ["standard", "deep"], "default": "standard", "example": "standard"}}}}}}, "responses": {"200": {"description": "Search completed successfully", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SearchResult"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimitExceeded"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/search/batch": {"post": {"summary": "Submit up to 5 search queries in a single call", "description": "Submits up to 5 natural language queries in a single API call. Each query is processed independently and returns the same result structure as /search. All queries in the batch use the same mode. Useful for parallel research across related topics without multiple round-trips. Cost per result is the same as individual /search calls.\n", "operationId": "searchBatch", "tags": ["Search"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["queries"], "properties": {"queries": {"type": "array", "description": "List of natural language search queries (max 5)", "minItems": 1, "maxItems": 5, "items": {"type": "string"}, "example": ["What is the current price of AWS Lambda per GB-second?", "Which cloud provider has the cheapest object storage in 2025?"]}, "mode": {"type": "string", "description": "Search depth applied to all queries in the batch. standard ($0.25/result) or deep ($0.40/result).\n", "enum": ["standard", "deep"], "default": "standard", "example": "standard"}}}}}}, "responses": {"200": {"description": "Batch search completed successfully", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "description": "Ordered list of search results corresponding to each input query. A result entry may contain an error field instead of answer/citations if an individual query failed.\n", "items": {"$ref": "#/components/schemas/SearchResult"}}}}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimitExceeded"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}}, "components": {"schemas": {"Citation": {"type": "object", "description": "A source citation supporting the answer", "properties": {"url": {"type": "string", "description": "Source URL", "example": "https://aws.amazon.com/lambda/pricing/"}, "title": {"type": "string", "description": "Page title of the source", "example": "AWS Lambda Pricing"}, "snippet": {"type": "string", "description": "Relevant text excerpt from the source", "example": "AWS Lambda counts a request each time it starts executing in response to an event notification."}}}, "SearchResult": {"type": "object", "properties": {"answer": {"type": "string", "description": "Synthesized, grounded answer to the query", "example": "As of Q4 2025, the m7i.large offers the best price-to-performance ratio for general-purpose EC2 workloads at $0.1008/hr in us-east-1."}, "citations": {"type": "array", "description": "Web sources used to ground the answer", "items": {"$ref": "#/components/schemas/Citation"}}, "tokens_used": {"type": "integer", "description": "Total tokens consumed processing this query", "example": 1240}, "mode": {"type": "string", "description": "Search mode used for this result", "enum": ["standard", "deep"], "example": "standard"}, "cost_usd": {"type": "number", "description": "Cost in USD charged for this result", "example": 0.25}}}, "ErrorResponse": {"type": "object", "properties": {"error": {"type": "string", "description": "Machine-readable error code", "example": "INVALID_QUERY"}, "message": {"type": "string", "description": "Human-readable error description", "example": "The query field is required and must be a non-empty string."}}}}, "responses": {"BadRequest": {"description": "Bad request - missing or invalid parameters", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "Unauthorized": {"description": "Unauthorized - invalid or missing API key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "RateLimitExceeded": {"description": "Rate limit exceeded - retry after the indicated interval", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "InternalServerError": {"description": "Internal server error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}}, "securitySchemes": {"ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key delivered via AWS Secrets Manager on Marketplace subscription"}}}, "security": [{"ApiKeyAuth": []}]}