# SearchPulse — Full API Documentation
# https://searchpulse.waltsoft.net
# Grounded web search: question → answer + citations

## Overview
SearchPulse uses Amazon Bedrock Web Search (Amazon's own web index, zero data egress)
+ GPT-5.5 synthesis to answer any question with cited sources.
No hallucinations — every claim is grounded in a real web source returned at query time.

## Endpoints

### GET /v1/search?q={question}&mode=standard
Grounded answer with citations. Uses Amazon Bedrock web index (≤400 output tokens, ≤3 searches).
- Price: $0.40/query (400000 atomic USDC)
- Required: q (URL-encoded question, max 500 chars)
- Optional: mode=standard (default) | mode=deep

### GET /v1/search?q={question}&mode=deep
Deep research answer with more sources. (≤1200 output tokens, ≤10 searches)
- Price: $0.40/query (400000 atomic USDC)
- Best for: complex comparisons, research summaries, multi-source topics

### GET /health
Health check. No authentication.

### GET /tryit?q={question}
Static demo result (3/day per IP, no real search performed).

## Authentication

### x402 Protocol (AI Agents, no signup)
Include X-PAYMENT header with USDC proof. Dual-chain: Solana + Base.

### API Key (Bearer sq_live_*)
Authorization: Bearer sq_live_...
Purchase at https://searchpulse.waltsoft.net

## Pricing

| Mode     | Price  | Atomic USDC | Output Limit |
|----------|--------|-------------|--------------|
| standard | $0.25  | 250000      | 400 tokens   |
| deep     | $0.40  | 400000      | 1200 tokens  |

## API Key Tiers

| Tier       | Credits | Price |
|------------|---------|-------|
| Starter    | 2500    | $25   |
| Pro        | 12500   | $100  |
| Enterprise | 50000   | $350  |

## Response Example

{
  "query": "What are the latest AWS Lambda cold-start mitigations?",
  "mode": "standard",
  "answer": "AWS Lambda now supports SnapStart for Java runtimes...",
  "citations": [
    { "title": "AWS Lambda SnapStart", "url": "https://aws.amazon.com/...", "start_index": 0, "end_index": 45 }
  ],
  "search_queries": ["AWS Lambda cold start 2026 mitigations"],
  "tokens_used": { "input": 487, "output": 312 },
  "timestamp": "2026-08-04T00:00:00.000Z"
}

## Data & Privacy
- No query text is stored permanently (only metadata: token counts, citation count)
- Powered by Amazon Bedrock Web Search (data stays within AWS)
- Zero external data egress by default