{"openapi":"3.0.3","info":{"title":"GapSmith Agent API","version":"1.0.0","description":"AI agent–accessible API for GapSmith venture intelligence. Authentication is via the x402 payment protocol — every request requires a Solana USDC payment proof in the X-PAYMENT header. Calls without payment receive HTTP 402 with payment requirements.\n\n## Two tiers\n\n- **Data API** (sub-dollar, synchronous): cached intelligence from past Scout runs. Returns results in <1s.\n- **Compute API** (few dollars, asynchronous): runs full pipelines on-demand. Returns 202 + jobId; agent polls for result.\n\n## x402 flow\n\n1. Agent makes request without `X-PAYMENT`.\n2. Server returns 402 with payment requirements (recipient ATA, amount, mint, network).\n3. Agent constructs SPL transferChecked tx, signs, submits to Solana.\n4. Agent retries the same request with `X-PAYMENT: <base64(JSON)>` header.\n5. Server verifies tx on-chain, processes request, returns 200.\n\nIdempotency: each tx_hash can only be used once. Retrying with the same `X-PAYMENT` returns the cached response (sync) or 409 (async).","contact":{"name":"GapSmith","url":"https://gapsmith.draftlabs.org"},"license":{"name":"MIT"}},"servers":[{"url":"https://gapsmith.draftlabs.org","description":"Production"}],"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"Base64-encoded JSON: {x402Version: 1, scheme: 'exact', network: 'solana'|'solana-devnet', payload: {txSignature: '<sig>'}}"}},"schemas":{"PaymentRequirements":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","enum":["solana","solana-devnet"]},"maxAmountRequired":{"type":"string","description":"Amount in USDC atomic units (6 decimals)"},"asset":{"type":"string","description":"USDC mint address"},"payTo":{"type":"string","description":"Merchant's USDC Associated Token Account"},"resource":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"}}},"Error402":{"type":"object","properties":{"x402Version":{"type":"integer","example":1},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequirements"}},"error":{"type":"string"}}},"GapItem":{"type":"object","description":"A synthesized venture opportunity from the Scout multi-agent pipeline. Includes the trend signal that surfaced the gap and the underlying pain signals.","properties":{"title":{"type":"string","example":"AI Agent Certification Layer for Enterprise Deployment"},"trend_signal":{"type":"object","properties":{"article":{"type":"string"},"source":{"type":"string"},"score":{"type":"number"},"insight":{"type":"string"}}},"pain_signals":{"type":"array","items":{"type":"object","properties":{"theme":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"signal_count":{"type":"integer"},"description":{"type":"string"}}}}}},"DailyBrief":{"type":"object","description":"Daily executive synthesis from the Scout pipeline.","properties":{"date":{"type":"string","format":"date"},"overview":{"type":"string"},"takeaway":{"type":"string"},"stats":{"type":"object"},"top_articles":{"type":"array"},"sector_heatmap":{"type":"object"},"narratives":{"type":"array"},"cross_signals":{"type":"array"}}},"PainCluster":{"type":"object","properties":{"theme":{"type":"string"},"description":{"type":"string"},"mentions":{"type":"integer"},"intensity":{"type":"string"}}},"TrendItem":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"velocity":{"type":"string"},"source":{"type":"string"}}},"KeywordItem":{"type":"object","properties":{"keyword":{"type":"string"},"count":{"type":"integer"}}},"AgentJob":{"type":"object","properties":{"jobId":{"type":"string","example":"fg_abc123"},"endpoint":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"progressPct":{"type":"integer","minimum":0,"maximum":100},"result":{"type":"object","nullable":true},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"txHash":{"type":"string"}}}}},"security":[{"x402":[]}],"paths":{"/api/v1/health":{"get":{"summary":"System health check (free)","description":"Probe LLM + search backend health BEFORE paying for a Compute API call. Free — no x402 required. Recommended pattern: agents call this first; if 503, wait for Retry-After before posting a Forge/Prove request, since the same preflight runs server-side and would reject the 402 advertisement anyway.","tags":["Health"],"security":[],"responses":{"200":{"description":"Healthy — safe to call paid Compute endpoints.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"llm":{"type":"object","properties":{"ok":{"type":"boolean"},"latency_ms":{"type":"integer"},"error":{"type":"string","nullable":true}}},"search":{"type":"object","nullable":true,"properties":{"ok":{"type":"boolean"},"error":{"type":"string","nullable":true}}},"server_time":{"type":"string","format":"date-time"}}}}}},"503":{"description":"Unhealthy — Compute API endpoints will reject 402 advertisements until system recovers. Includes Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying. 30 for transient upstream issues; 600 for config errors that need operator intervention."}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"errorClass":{"type":"string","enum":["upstream","config"],"description":"upstream = retry later; config = operator must fix (don't retry)"},"llm":{"type":"object"},"search":{"type":"object","nullable":true},"server_time":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/scout/gaps":{"get":{"summary":"Market gap intelligence","description":"Aggregated market gaps from recent multi-agent scans. Cached — returns instantly.","tags":["Data API"],"parameters":[{"name":"sector","in":"query","schema":{"type":"string"},"description":"Filter by sector tag (e.g. 'ai-ml', 'fintech')"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Gaps returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"gaps":{"type":"array","items":{"$ref":"#/components/schemas/GapItem"}},"count":{"type":"integer"},"generatedFrom":{"type":"string","format":"date-time","nullable":true},"sector":{"type":"string","nullable":true}}}}}},"402":{"description":"Payment required (0.10 USDC)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error402"}}}}}}},"/api/v1/scout/pain-clusters":{"get":{"summary":"Pain cluster intelligence","description":"Recurring themes from real user complaints (Reddit, HN, forums). Cached — returns instantly.","tags":["Data API"],"parameters":[{"name":"sector","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Pain clusters returned","content":{"application/json":{"schema":{"type":"object","properties":{"painClusters":{"type":"array","items":{"$ref":"#/components/schemas/PainCluster"}},"count":{"type":"integer"},"generatedFrom":{"type":"string","format":"date-time","nullable":true}}}}}},"402":{"description":"Payment required (0.10 USDC)"}}}},"/api/v1/scout/trends":{"get":{"summary":"Trend signals","description":"Emerging market shifts from recent scans. Cached — returns instantly.","tags":["Data API"],"parameters":[{"name":"sector","in":"query","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":7}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Trends returned"},"402":{"description":"Payment required (0.10 USDC)"}}}},"/api/v1/sectors":{"get":{"summary":"List sectors with cached data (free)","description":"Discovery endpoint — call this first to find which sector tags actually have cached Scout data, so you don't pay USDC for an empty result. No payment required.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Sector list","content":{"application/json":{"schema":{"type":"object","properties":{"sectors":{"type":"array","items":{"type":"object","properties":{"sector":{"type":"string"},"report_count":{"type":"integer"},"latest_report":{"type":"string","format":"date-time"},"gaps_count":{"type":"integer"}}}},"total_reports":{"type":"integer"},"latest_overall":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"/api/v1/scout/brief":{"get":{"summary":"Daily executive brief (richest data)","description":"Analyst-grade synthesis of the most recent Scout run. Includes overview narrative, takeaway, sector heatmap, narratives, cross-signals.","tags":["Data API"],"responses":{"200":{"description":"Brief returned","content":{"application/json":{"schema":{"type":"object","properties":{"brief":{"$ref":"#/components/schemas/DailyBrief"},"generatedFrom":{"type":"string","format":"date-time"},"sectors":{"type":"array","items":{"type":"string"}}}}}}},"402":{"description":"Payment required (0.20 USDC)"},"404":{"description":"No completed brief available"}}}},"/api/v1/scout/keywords":{"get":{"summary":"Keyword intelligence","description":"Top keywords by aggregate occurrence across recent scans. Cached — returns instantly.","tags":["Data API"],"parameters":[{"name":"sector","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Keywords returned"},"402":{"description":"Payment required (0.05 USDC)"}}}},"/api/v1/forge/ideate":{"post":{"summary":"Run a Forge brainstorm session (async)","description":"Triggers the multi-agent Forge pipeline for the given context. Returns 202 + jobId immediately; pipeline runs in background (~30 min). Poll /api/v1/jobs/{jobId} for progress + result.","tags":["Compute API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sectors":{"type":"array","items":{"type":"string"}},"context":{"type":"string","maxLength":10000},"product_modes":{"type":"array","items":{"type":"string"}},"session_config":{"description":"Optional SESSION_CONFIG the engine calibrates against. Accepts EITHER a structured object (preferred — enum-validated) OR raw SESSION_CONFIG.md markdown (backward-compatible). Empty falls back to default Small Team / $10K / 4-8 weeks / $100K.","oneOf":[{"type":"object","additionalProperties":false,"properties":{"profile":{"type":"string","enum":["Solo","Small Team (2-3)","Small Team (4-5)","Funded Team (6-15)","Enterprise"],"description":"Team profile — calibrates Analyst's lean-feasibility math."},"budget":{"type":"string","enum":["$1K","$5K","$10K","$25K","$50K","$100K+"],"description":"MVP budget cap. LEAN_FIT band scales proportionally to this value."},"timeline":{"type":"string","enum":["2 weeks","4 weeks","4-8 weeks","8-12 weeks","3-6 months"],"description":"Validation timeline."},"revenue_threshold":{"type":"string","enum":["$10K/year","$50K/year","$100K/year","$500K/year","$1M+/year"],"description":"Year-1 revenue target. Ideas projecting below this are tagged LOW_ROI."},"founder_signal":{"type":"string","maxLength":2000,"description":"Free-form founder background / unfair-advantage statement."}},"example":{"profile":"Solo","budget":"$1K","timeline":"3-6 months","revenue_threshold":"$50K/year","founder_signal":"8 years payments infra, ex-Stripe."}},{"type":"string","maxLength":5000,"description":"Raw SESSION_CONFIG.md. Lines like `Profile: Solo`, `Budget: $1K`, `Timeline: 3-6 months`, `Revenue_threshold: $50K/year`, optional `Signal: ...`."}]},"webhook_url":{"type":"string","format":"uri","description":"Optional: POST result here when done"}}}}}},"responses":{"202":{"description":"Job accepted; poll status","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending"]},"statusUrl":{"type":"string"},"etaMinutes":{"type":"integer"}}}}}},"402":{"description":"Payment required (15 USDC)"},"422":{"description":"Body failed validation (no payment burned)"},"503":{"description":"Upstream LLM or search backend currently unhealthy. Server preflight refused to advertise 402 — agent did NOT pay. Includes Retry-After header. Hit GET /api/v1/health to check readiness before retrying."}}}},"/api/v1/prove/debate":{"post":{"summary":"Run a Prove debate session (async)","description":"Triggers the 6-persona Prove pipeline (Proposer, Challenger, Analyst, Reviewer, Defender, Strategist) to stress-test a single idea across up to 3 rounds of search-augmented debate + final voting. Returns 202 + jobId immediately; pipeline runs ~60 min. Poll /api/v1/jobs/{jobId} for progress + result.","tags":["Compute API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idea"],"properties":{"idea":{"type":"string","minLength":10,"maxLength":10000,"description":"The idea / product brief to debate. Multi-line markdown is fine — the Proposer reads this verbatim as the seed."},"session_config":{"description":"Optional SESSION_CONFIG (object preferred, string accepted). Same shape as /forge/ideate.","oneOf":[{"type":"object","additionalProperties":false,"properties":{"profile":{"type":"string","enum":["Solo","Small Team (2-3)","Small Team (4-5)","Funded Team (6-15)","Enterprise"]},"budget":{"type":"string","enum":["$1K","$5K","$10K","$25K","$50K","$100K+"]},"timeline":{"type":"string","enum":["2 weeks","4 weeks","4-8 weeks","8-12 weeks","3-6 months"]},"revenue_threshold":{"type":"string","enum":["$10K/year","$50K/year","$100K/year","$500K/year","$1M+/year"]},"founder_signal":{"type":"string","maxLength":2000}}},{"type":"string","maxLength":5000}]},"webhook_url":{"type":"string","format":"uri","description":"Optional: POST result here when done"}}}}}},"responses":{"202":{"description":"Job accepted; poll status. When complete, result.verdict ∈ { APPROVED, CONDITIONAL_APPROVED, REJECTED, PIVOT_OUT }. PIVOT_OUT means a panelist self-declared the idea unsalvageable mid-debate (no final vote was taken); result.report.pivot_report holds the suggested new direction. APPROVED/CONDITIONAL_APPROVED → result.report.output is the execution roadmap, result.report.summary is the 1-page Lean Canvas. REJECTED (vote-driven) → result.report.output is a kill brief with top 3 reasons + salvage paths, result.report.summary is a 1-page decision brief.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending"]},"statusUrl":{"type":"string"},"etaMinutes":{"type":"integer","example":60},"proveSessionId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"Payment required (25 USDC)"},"422":{"description":"Body failed validation (no payment burned)"},"503":{"description":"Upstream LLM or search backend currently unhealthy. Server preflight refused to advertise 402 — agent did NOT pay. Includes Retry-After header. Hit GET /api/v1/health to check readiness before retrying."}}}},"/api/v1/jobs/{jobId}":{"get":{"summary":"Poll an async job's status","description":"Free endpoint — jobId acts as a capability token. No X-PAYMENT required.","tags":["Jobs"],"security":[],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentJob"}}}},"404":{"description":"Job not found"}}}}}}