{"openapi":"3.1.0","info":{"title":"YSAERE Intelligence API","version":"1.0.0","description":"AI-powered intelligence reports for Competitive Intelligence, Due Diligence, and Commercial Real Estate deal analysis. Every response includes Trust Layer provenance verification.","contact":{"name":"Ysaere, Inc. (Ysaere API)","url":"https://app.ysaere.com/developer","email":"developers@ysaere.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.ysaere.com/v1","description":"Production"},{"url":"http://localhost:3000/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"paths":{"/pricing":{"get":{"tags":["Pricing"],"summary":"List machine pricing quotes (0 credits, no auth)","description":"Public catalog of debiting intel SKUs with credits, USD/USDC, settlement_rails, and custody statement. x402 appears only when X402_ENABLED and configured.","operationId":"listMachinePricing","security":[],"responses":{"200":{"description":"Pricing catalog","content":{"application/json":{"schema":{"type":"object"},"example":{"data":{"offerings":[{"sku":"retail-insights","credits":25,"usd":"2.50","settlement_rails":["credits"],"custody":"none"}],"custody":"none"},"usage":{"credits_consumed":0}}}}}}}},"/pricing/{sku}":{"get":{"tags":["Pricing"],"summary":"Quote one SKU (0 credits, no auth)","operationId":"quoteMachineSku","security":[],"parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","example":"retail-insights"}}],"responses":{"200":{"description":"SKU quote"},"404":{"description":"Unknown SKU"}}}},"/intel/estimate":{"post":{"tags":["Intelligence"],"summary":"Estimate credits before a debiting intel run (0 credits)","description":"Dry-run credit cost. Pass `endpoint` (REST suffix, e.g. ci-report) or `tool` (MCP name, e.g. company_intelligence). Omit both for the debiting catalog. Never debits.","operationId":"estimateIntelCredits","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","example":"angel-report"},"tool":{"type":"string","example":"angel_intelligence"}}},"examples":{"angel":{"value":{"endpoint":"angel-report"}},"ci_mcp_tool":{"value":{"tool":"company_intelligence"}},"catalog":{"value":{}}}}}},"responses":{"200":{"description":"Estimate or catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateResponse"},"example":{"data":{"endpoint":"angel-report","credits":50,"swarm_type":"CI_ANGEL","notes":"Angel Intelligence — pre-seed/seed triage.","debiting":true,"estimated":true,"debit_will_occur":true},"usage":{"credits_consumed":0}}}}},"400":{"description":"Unknown endpoint or tool"},"401":{"description":"Unauthorized"}}}},"/intel/ci-report":{"post":{"tags":["Intelligence"],"summary":"Competitive Intelligence Report (100 credits)","description":"Runs a full 5-agent CI swarm: Scout, Researcher, Mapper, Analyst, Compiler. Prefer POST /intel/estimate first. Poll GET /reports/{run_id} or MCP wait_for_report until completed.","operationId":"createCIReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Stripe","config":{"focus_areas":["market_position","pricing"]}}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"},"example":{"data":{"run_id":"00000000-0000-4000-8000-000000000001","status":"queued","endpoint":"ci-report","swarm_type":"CI","estimated_time_seconds":120,"poll_url":"/v1/reports/00000000-0000-4000-8000-000000000001"},"usage":{"credits_consumed":100,"balance_remaining":50}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits — machine body includes required, balance, topup_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsResponse"},"example":{"success":false,"error":{"code":"INSUFFICIENT_CREDITS","machine_code":"insufficient_credits","message":"Insufficient credits. Required: 100, Available: 12","required":100,"balance":12,"topup_url":"https://app.ysaere.com/account/usage"},"required":100,"balance":12,"topup_url":"https://app.ysaere.com/account/usage"}}}},"409":{"description":"Idempotency-Key reused with a different body"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":256},"description":"Replay-safe retries for debiting POSTs. Same key + same body returns the prior 202 without a second debit."}]}},"/intel/dd-report":{"post":{"tags":["Intelligence"],"summary":"Due Diligence Report (200 credits)","operationId":"createDDReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/market-report":{"post":{"tags":["Intelligence"],"summary":"Market Intelligence Report (150 credits)","description":"Runs a full 7-agent market/landscape CI swarm: Scout, Researcher, Topology Mapper, Capital Flow Analyst, Emerging Entrants Scout, Adjacent Attackers Analyst, Compiler.","operationId":"createMarketReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"US cybersecurity market 2026"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/angel-report":{"post":{"tags":["Intelligence"],"summary":"Angel Intelligence Report (50 credits)","description":"Runs a 5-agent Angel swarm (pre-seed/seed triage + syndicate memo). Prefer POST /intel/estimate first. Poll GET /reports/{run_id} until completed.","operationId":"createAngelReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Acme AI (pre-seed)"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"},"example":{"data":{"run_id":"00000000-0000-4000-8000-0000000000aa","status":"queued","endpoint":"angel-report","swarm_type":"CI_ANGEL","estimated_time_seconds":120,"poll_url":"/v1/reports/00000000-0000-4000-8000-0000000000aa"},"usage":{"credits_consumed":50,"balance_remaining":100}}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsResponse"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":256}}]}},"/intel/angel-deep-report":{"post":{"tags":["Intelligence"],"summary":"Angel Deep Report (90 credits)","description":"Angel Intelligence plus community-traction signal and a deterministic traction score.","operationId":"createAngelDeepReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Acme AI (pre-seed)"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/quick-brief":{"post":{"tags":["Intelligence"],"summary":"Quick Brief — sync (20 credits)","description":"Cheap M2M sync triage brief on NVIDIA NIM Super (Nemotron). Returns a short JSON memo in one response (not a swarm — no poll). Body: `{ \"target\": \"OpenAI\", \"focus\"?: \"…\", \"context\"?: \"…\" }`. Informational only — not verified fact or professional advice. Prefer POST /intel/estimate first.","operationId":"createQuickBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string","maxLength":200},"focus":{"type":"string","maxLength":500},"context":{"type":"string","maxLength":4000}}},"example":{"target":"OpenAI","focus":"enterprise distribution risk","context":"Caller is screening for a partnership memo this week."}}}},"responses":{"200":{"description":"Quick brief","content":{"application/json":{"schema":{"type":"object","required":["data","usage"],"properties":{"data":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"target":{"type":"string"},"brief":{"type":"object","properties":{"headline":{"type":"string"},"summary":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"watch_items":{"type":"array","items":{"type":"string"}},"confidence":{"type":"string","enum":["low","medium","high"]}}},"connector":{"type":"string"},"model":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/Usage"}}}}}},"402":{"description":"Insufficient credits"},"503":{"description":"NIM unavailable or unusable brief — no credits charged"}}}},"/intel/sourced-brief":{"post":{"tags":["Intelligence"],"summary":"Sourced Brief — sync (40 credits)","description":"M2M sync brief grounded in Exa web retrieval (± optional Vault chunks), then NVIDIA NIM Super. Returns JSON memo + citations in one response (not a swarm — no poll). Body: `{ \"target\": \"…\", \"focus\"?: \"…\", \"context\"?: \"…\", \"sources\"?: [\"web\",\"vault\"], \"file_ids\"?: [\"…\"] }`. Default sources = `[\"web\"]`. Informational only — not verified fact. Prefer POST /intel/estimate first.","operationId":"createSourcedBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string","maxLength":200},"focus":{"type":"string","maxLength":500},"context":{"type":"string","maxLength":4000},"sources":{"type":"array","items":{"type":"string","enum":["web","vault"]},"minItems":1},"file_ids":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Optional Vault file scope when sources includes vault"}}},"example":{"target":"OpenAI","focus":"enterprise distribution","sources":["web"]}}}},"responses":{"200":{"description":"Sourced brief with citations","content":{"application/json":{"schema":{"type":"object","required":["data","usage"],"properties":{"data":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"target":{"type":"string"},"brief":{"type":"object"},"retrieve":{"type":"object"},"connector":{"type":"string"},"model":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/Usage"}}}}}},"402":{"description":"Insufficient credits"},"503":{"description":"Exa/NIM unavailable or unusable brief — no credits charged"}}}},"/intel/vault-search":{"post":{"tags":["Intelligence"],"summary":"Vault Search — sync (5 credits)","description":"Tenant-scoped Vault chunk search over `file_chunks` (embeddings). No LLM narrative — returns ranked chunks only. Body: `{ \"query\": \"…\", \"limit\"?: 8, \"min_similarity\"?: 0.35, \"file_ids\"?: [\"…\"] }`.","operationId":"searchVault","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":2000},"limit":{"type":"integer","minimum":1,"maximum":20},"min_similarity":{"type":"number","minimum":0,"maximum":0.99},"file_ids":{"type":"array","items":{"type":"string"},"maxItems":50}}},"example":{"query":"lease expiration schedule","limit":8}}}},"responses":{"200":{"description":"Ranked Vault chunks","content":{"application/json":{"schema":{"type":"object","required":["data","usage"],"properties":{"data":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"chunks":{"type":"array","items":{"type":"object"}}}},"usage":{"$ref":"#/components/schemas/Usage"}}}}}},"402":{"description":"Insufficient credits"},"503":{"description":"Embeddings unavailable — no credits charged"}}}},"/intel/classify":{"post":{"tags":["Intelligence"],"summary":"Entity Classify — sync (10 credits)","description":"Cheap M2M sync classify on NVIDIA NIM Nano. Returns entity labels in one response (not a swarm — no poll). Body: `{ \"target\": \"OpenAI\" }` or `{ \"candidates\": [{ \"name\": \"…\", \"context\": \"…\" }] }` (max 20). Informational labels only — not verified fact. Prefer POST /intel/estimate first.","operationId":"classifyEntities","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["target"],"properties":{"target":{"type":"string","maxLength":200},"context":{"type":"string","maxLength":2000}}},{"type":"object","required":["candidates"],"properties":{"candidates":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"context":{"type":"string","maxLength":2000}}}}}}]},"example":{"target":"OpenAI","context":"AI research lab founded by Sam Altman"}}}},"responses":{"200":{"description":"Classification results","content":{"application/json":{"schema":{"type":"object","required":["data","usage"],"properties":{"data":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"confidence":{"type":"number"},"reasoning":{"type":"string"}}}},"connector":{"type":"string"},"model":{"type":"string"},"disclaimer":{"type":"string"}}},"provenance":{"type":"object"},"usage":{"$ref":"#/components/schemas/Usage"}}}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsResponse"}}}},"503":{"description":"NVIDIA NIM unavailable — no credits charged"}}}},"/intel/security-scan":{"post":{"tags":["Intelligence"],"summary":"Security Assessment (75 credits)","description":"Public OSINT security diligence brief (not a pen test or attestation). Poll GET /reports/{run_id} until completed.","operationId":"createSecurityScan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Stripe"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/trust-check":{"post":{"tags":["Intelligence"],"summary":"Trust Check (100 credits)","description":"Entity stewardship diligence. Not publicly shareable. MCP tool is opt-in (MCP_TRUST_CHECK_ENABLED).","operationId":"createTrustCheck","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Acme Corp"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/retail-insights":{"post":{"tags":["Intelligence"],"summary":"Retail Insights (25 credits)","description":"Listed SEC issuer snapshot (Light). Informational only — not investment advice. When X402_ENABLED, may settle via x402 (Accept-Payment: x402 / Payment-Signature) instead of credits. MCP tools opt-in via MCP_RETAIL_TOOLS_ENABLED.","operationId":"createRetailInsights","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"AAPL"}}}},"parameters":[{"name":"Accept-Payment","in":"header","required":false,"schema":{"type":"string","example":"x402"},"description":"Request an x402 challenge when credits are insufficient (requires X402_ENABLED)."},{"name":"Payment-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 JSON payment payload after facilitator pay. On settle success, credits are not debited."}],"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}},"402":{"description":"Insufficient credits and/or x402_payment_required challenge","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/InsufficientCreditsResponse"},{"$ref":"#/components/schemas/X402PaymentRequiredResponse"}]}}}}}}},"/intel/retail-insights-deep":{"post":{"tags":["Intelligence"],"summary":"Retail Insights Deep Dive (75 credits)","description":"Deep Dive — filing body excerpts + companyFacts + Form 4 timeline. Informational only — not investment advice.","operationId":"createRetailInsightsDeep","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"AAPL"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/politician-trades":{"post":{"tags":["Intelligence"],"summary":"Congress Insider Trades (50 credits)","description":"STOCK Act public trade disclosures for one named Member of Congress. Pass the Member name as `target`. Informational only — not investment advice.","operationId":"createPoliticianTrades","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Nancy Pelosi"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/cre/deal-brief":{"post":{"tags":["CRE Intelligence"],"summary":"CRE Deal Brief (250 credits)","description":"Runs the generalist CRE Deal Intelligence swarm (6 agents). When config includes asset-class hints (e.g. config.cre.om_facts.asset_class or propertyType), the worker may auto-route to a specialist silo. Prefer the dedicated silo endpoints when the asset class is already known.","operationId":"createCREDealBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"123 Main St, New York, NY","config":{"property_type":"office"}}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/cre/net-lease-brief":{"post":{"tags":["CRE Intelligence"],"summary":"Net-Lease Deal Brief (250 credits)","description":"Runs the Net-Lease specialist CRE swarm (credit-tenant bond underwriting). Same credit cost as CRE Deal Brief. Explicit SKU — does not depend on OM auto-route.","operationId":"createNetLeaseDealBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"4500 Retail Plaza, Dallas, TX"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/cre/multifamily-brief":{"post":{"tags":["CRE Intelligence"],"summary":"Multifamily Deal Brief (250 credits)","description":"Runs the Multifamily specialist CRE swarm (unit mix / T-12 / value-add). Same credit cost as CRE Deal Brief. Explicit SKU — does not depend on OM auto-route.","operationId":"createMultifamilyDealBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"1200 Oak Apartments, Austin, TX"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/cre/self-storage-brief":{"post":{"tags":["CRE Intelligence"],"summary":"Self-Storage Deal Brief (250 credits)","description":"Runs the Self-Storage specialist CRE swarm (occupancy / ECRI / ancillary / supply). Same credit cost as CRE Deal Brief. Explicit SKU — does not depend on OM auto-route.","operationId":"createSelfStorageDealBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Storage Depot, Phoenix, AZ"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/marketplace/agents":{"get":{"tags":["Marketplace"],"summary":"Discover published agents","description":"Search/browse published marketplace agents. Returns agents with id, slug, description, and credit cost.","operationId":"searchMarketplaceAgents","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":20}}],"responses":{"200":{"description":"List of published agents"}}}},"/marketplace/agents/{idOrSlug}/run":{"post":{"tags":["Marketplace"],"summary":"Run a published marketplace agent","description":"Executes a published agent by id or slug. Packaged agents need no input ({}); parameterized agents require a target. Returns a run_id — poll /reports/{runId}.","operationId":"runMarketplaceAgent","parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"},"example":{"target":"Acme Corp"}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}}}}}},"/intel/company-profile":{"post":{"tags":["CI Agents"],"summary":"Company Profile (2 credits)","operationId":"companyProfile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/competitive-landscape":{"post":{"tags":["CI Agents"],"summary":"Competitive Landscape (4 credits)","operationId":"competitiveLandscape","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/financial-analysis":{"post":{"tags":["CI Agents"],"summary":"Financial Analysis (3 credits)","operationId":"financialAnalysis","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/leadership-check":{"post":{"tags":["CI Agents"],"summary":"Leadership Check (3 credits)","operationId":"leadershipCheck","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/threat-assessment":{"post":{"tags":["CI Agents"],"summary":"Threat Assessment (5 credits)","operationId":"threatAssessment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/vendor-risk":{"post":{"tags":["CI Agents"],"summary":"Vendor Risk (4 credits)","operationId":"vendorRisk","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/cre/property-profile":{"post":{"tags":["CRE Agents"],"summary":"Property Profile (5 credits)","operationId":"crePropertyProfile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/cre/market-analysis":{"post":{"tags":["CRE Agents"],"summary":"Market Analysis (8 credits)","operationId":"creMarketAnalysis","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/cre/financial-model":{"post":{"tags":["CRE Agents"],"summary":"Financial Model (10 credits)","operationId":"creFinancialModel","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/cre/risk-assessment":{"post":{"tags":["CRE Agents"],"summary":"Risk Assessment (8 credits)","operationId":"creRiskAssessment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/intel/cre/lease-analysis":{"post":{"tags":["CRE Agents"],"summary":"Lease Analysis (15 credits)","operationId":"creLeaseAnalysis","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelRequest"}}}},"responses":{"202":{"description":"Queued"}}}},"/account/balance":{"get":{"tags":["Account"],"summary":"Get credit balance","operationId":"getBalance","responses":{"200":{"description":"Current balance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balance":{"type":"integer"},"lifetime_used":{"type":"integer"}}}}}}}}}}},"/account/usage":{"get":{"tags":["Account"],"summary":"Get API usage statistics","operationId":"getUsage","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"Usage stats"}}}},"/reports/{id}":{"get":{"tags":["Reports"],"summary":"Get report by ID","operationId":"getReport","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report with provenance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"404":{"description":"Not found"}}}},"/reports/{id}/provenance":{"get":{"tags":["Reports"],"summary":"Get trust verification chain","operationId":"getProvenance","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Provenance chain"}}}},"/runs/{runId}/eval":{"get":{"tags":["Eval"],"summary":"Get the eval score, judgements, and provenance for a run","description":"Tenant-isolated. Returns the canonical EvalResult plus any LLM-judge results and the provenance chain that was scored.","operationId":"getRunEval","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Eval result with provenance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalResultResponse"}}}},"404":{"description":"Run not found or no eval recorded yet"}}}},"/runs/{runId}/trust-receipt":{"get":{"tags":["Eval"],"summary":"Get (or generate) the HMAC-signed trust receipt for a run","description":"Idempotent: returns the existing receipt if one exists, otherwise generates one. Returns metadata + verify URL + download URL — the PDF itself is at /api/swarms/{runId}/trust-receipt.pdf.","operationId":"getTrustReceipt","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Trust receipt metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustReceiptResponse"}}}},"404":{"description":"Run not found"},"409":{"description":"Run has no eval or provenance — receipt cannot be assembled yet"}}}},"/verify/{signature}":{"get":{"tags":["Verify"],"summary":"Publicly verify a trust receipt signature (no auth)","description":"Rate-limited per IP (60 calls/hour). Recomputes the HMAC over the canonical payload and checks the provenance chain hash. Returns `verified: true|false` plus an opaque failure reason. The full canonical payload is included when verified=true so anyone can render the rubric.","operationId":"verifySignature","security":[],"parameters":[{"name":"signature","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"429":{"description":"Rate limit exceeded"}}}},"/verify/{runId}/{signature}":{"get":{"tags":["Verify"],"summary":"Publicly verify a trust receipt scoped to a specific run ID","description":"Same as /v1/verify/{signature} but ALSO checks the run ID in the URL matches the receipt — useful when both are printed on a PDF and the verifier wants extra assurance.","operationId":"verifySignatureWithRun","security":[],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"signature","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"429":{"description":"Rate limit exceeded"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","operationId":"listWebhooks","responses":{"200":{"description":"Webhook list"}}},"post":{"tags":["Webhooks"],"summary":"Register webhook","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"default":["report.completed"]}}}}}},"responses":{"201":{"description":"Webhook created with signing secret"}}}},"/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete webhook","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (ysa_prod_* for production, ysa_test_* for sandbox; legacy zyv_* keys still accepted)"}},"schemas":{"IntelRequest":{"type":"object","required":["target"],"properties":{"target":{"type":"string","description":"Company name, domain, or property address"},"config":{"type":"object","description":"Optional configuration","additionalProperties":true}}},"AsyncResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed"]},"endpoint":{"type":"string"},"poll_url":{"type":"string"},"estimated_time_seconds":{"type":"integer"}}},"usage":{"type":"object","properties":{"credits_consumed":{"type":"integer"},"balance_remaining":{"type":"integer"}}}}},"ReportResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"run_id":{"type":"string"},"status":{"type":"string"},"report":{"type":"object"},"quality_score":{"type":"number"}}},"provenance":{"type":"object","properties":{"verified":{"type":"boolean"},"agents":{"type":"array","items":{"type":"string"}},"content_hashes":{"type":"object"},"sources":{"type":"array"}}}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"EstimateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"endpoint":{"type":"string"},"credits":{"type":"integer"},"swarm_type":{"type":"string","nullable":true},"notes":{"type":"string"},"debiting":{"type":"boolean"},"estimated":{"type":"boolean"},"debit_will_occur":{"type":"boolean"},"catalog":{"type":"array","items":{"type":"object"}}}},"usage":{"type":"object","properties":{"credits_consumed":{"type":"integer","const":0}}}}},"InsufficientCreditsResponse":{"type":"object","description":"HTTP 402 — agents should read flat required/balance/topup_url","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string","const":"INSUFFICIENT_CREDITS"},"machine_code":{"type":"string","const":"insufficient_credits"},"message":{"type":"string"},"required":{"type":"integer"},"balance":{"type":"integer"},"topup_url":{"type":"string","format":"uri"}}},"required":{"type":"integer"},"balance":{"type":"integer"},"topup_url":{"type":"string","format":"uri"}}},"X402PaymentRequiredResponse":{"type":"object","description":"HTTP 402 when X402_ENABLED — machine_code x402_payment_required. Retry with Payment-Signature after facilitator pay. Allowlisted: classify, quick-brief, retail-insights. Default facilitator x402.org (Option A).","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string","const":"PAYMENT_REQUIRED"},"machine_code":{"type":"string","const":"x402_payment_required"},"message":{"type":"string"},"x402":{"type":"object","properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string","enum":["base-sepolia","base"]},"asset":{"type":"string","const":"USDC"},"pay_to":{"type":"string"},"max_amount_required":{"type":"string","example":"2.50"},"resource":{"type":"string"},"resource_hash":{"type":"string"},"facilitator":{"type":"string","const":"coinbase"},"expires_at":{"type":"string","format":"date-time"}}},"credits_alternative":{"type":"object","properties":{"required":{"type":"integer"},"balance":{"type":"integer"},"topup_url":{"type":"string","format":"uri"}}}}}}},"EvalResultResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"swarm_type":{"type":"string"},"target":{"type":"string"},"status":{"type":"string"},"overall_score":{"type":"number","description":"0–100"},"prompt_snapshot_hash":{"type":"string"},"breakdown":{"type":"object","properties":{"structural":{"type":"number"},"content":{"type":"number"},"calibration":{"type":"number"},"sections":{"type":"array","items":{"type":"object","additionalProperties":true}},"agents":{"type":"object","additionalProperties":true}}},"judgements":{"type":"array","items":{"type":"object","properties":{"section_id":{"type":"string"},"judge_model":{"type":"string"},"overall_score":{"type":"number"},"factuality_score":{"type":"number"},"citation_score":{"type":"number"},"reasoning_score":{"type":"number"},"commentary":{"type":"string"}}}}}},"provenance":{"type":"object","properties":{"verified":{"type":"boolean"},"agents":{"type":"array","items":{"type":"string"}},"content_hashes":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array"},"chain":{"type":"array"}}},"usage":{"type":"object","properties":{"credits_consumed":{"type":"integer"},"balance_remaining":{"type":"integer","nullable":true}}}}},"TrustReceiptResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"signature":{"type":"string","description":"base64url HMAC-SHA256"},"generated_at":{"type":"string","format":"date-time"},"overall_score":{"type":"number","nullable":true},"prompt_hash":{"type":"string","nullable":true},"verify_url":{"type":"string","description":"Public verify URL (web)"},"api_verify_url":{"type":"string","description":"Public verify URL (API)"},"download_url":{"type":"string","description":"PDF download path"},"is_sandbox":{"type":"boolean"}}},"usage":{"type":"object","properties":{"credits_consumed":{"type":"integer"},"balance_remaining":{"type":"integer","nullable":true}}}}},"VerifyResponse":{"type":"object","properties":{"verified":{"type":"boolean"},"run_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time","nullable":true},"overall_score":{"type":"number","nullable":true},"failure_reason":{"type":"string","nullable":true,"description":"Opaque failure reason. One of: not_found | tampered | hash_chain_mismatch | run_id_mismatch | rate_limited | verification_error."},"payload":{"type":"object","description":"Full canonical payload (only when verified=true)","additionalProperties":true}}}}}}