{
  "openapi": "3.1.0",
  "info": {
    "title": "Zambo API",
    "version": "4.0.0",
    "description": "Give your AI hands. Zambo exposes a canonical MCP endpoint and public HTTPS contracts for live tools, continuity, approval boundaries, and truthful receipts.",
    "contact": {
      "name": "Brennan Zambo",
      "url": "https://zambo.dev",
      "email": "brennanzambo@zambo.dev"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "x-logo": {
      "url": "https://zambo.dev/og-v3.png"
    },
    "x-guidance": "Zambo offers a Day Pass - $0.99 in Base USDC for 24-hour access to the Zambo MCP connection (138 tools total, 19 on the default surface) - and Zambo Pass at $29/month or $290/year, with $19/month for verified $ZAMBO holders. Not per call; one Day Pass payment covers 24 hours. Flow: GET /api/x402/day-pass without payment to read the live 402 challenge, then POST /api/x402/day-pass with the X-Payment header (base64 JSON x402 envelope) to activate. Every call returns a verifiable receipt."
  },
  "externalDocs": {
    "description": "Full LLM context and integration guide",
    "url": "https://zambo.dev/llms-full.txt"
  },
  "servers": [
    {
      "url": "https://zambo.dev",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "universal",
      "description": "Universal routing endpoint - one call, all products"
    },
    {
      "name": "Discovery",
      "description": "Agent and capability discovery, routing, traction data"
    },
    {
      "name": "ZAMBOT",
      "description": "Agent Evolution Engine - swarm wisdom sparks"
    },
    {
      "name": "ZAMBRO",
      "description": "Opportunity scanner and builder intelligence"
    },
    {
      "name": "ProvibeCode",
      "description": "AI code audit with Provibe Score"
    },
    {
      "name": "LeadSignal",
      "description": "AI lead generation for contractors"
    },
    {
      "name": "GEO",
      "description": "Crawl telemetry and discoverability endpoints"
    },
    {
      "name": "Capabilities",
      "description": "Full endpoint catalog"
    }
  ],
  "paths": {
    "/api/zambo": {
      "post": {
        "tags": [
          "universal"
        ],
        "operationId": "zamboUniversal",
        "summary": "Universal API - one call, all products",
        "description": "Send a natural-language need for truthful routing. Use the canonical MCP endpoint for receipt-backed execution. Free limits apply.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "need"
                ],
                "properties": {
                  "need": {
                    "type": "string",
                    "description": "Natural language description of what you need",
                    "example": "Audit my public code hosting repo for security issues"
                  },
                  "context": {
                    "type": "object",
                    "description": "Optional extra context (repo_url, goal, trade, city, wallet, domain)"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "markdown"
                    ],
                    "default": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expert structured response with product routing and results"
          },
          "429": {
            "description": "Rate limit reached - 20 free/day/IP"
          }
        }
      },
      "get": {
        "tags": [
          "universal",
          "Discovery"
        ],
        "operationId": "zamboApiDocs",
        "summary": "Zambo API documentation and routing guide",
        "description": "Returns full documentation for Zambo's 138 MCP tools (19 on the default surface), endpoints, and routing logic.",
        "responses": {
          "200": {
            "description": "Full API docs with product catalog and routing guide"
          }
        }
      }
    },
    "/api/ask": {
      "get": {
        "tags": [
          "universal",
          "Discovery"
        ],
        "operationId": "zamboAskGet",
        "summary": "Natural language Q&A about Zambo",
        "description": "Ask any question about Zambo - tools, pricing, routing, capabilities, how-tos. Returns structured answer with products_mentioned and CTA. 20 free/day/IP, no auth.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your question",
            "example": "What is ZAMBRO and how do I use the API?"
          }
        ],
        "responses": {
          "200": {
            "description": "Structured answer with products_mentioned and routing CTA"
          }
        }
      },
      "post": {
        "tags": [
          "universal",
          "Discovery"
        ],
        "operationId": "zamboAskPost",
        "summary": "Natural language Q&A (POST variant)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "description": "Your question"
                  },
                  "context": {
                    "type": "string",
                    "description": "Optional extra context"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured answer with routing"
          }
        }
      }
    },
    "/api/intro": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getIntro",
        "summary": "LLM system prompt injection - full routing context",
        "description": "Returns the complete Zambo routing guide optimized for injection into any LLM system prompt. Includes for_llm_system_prompt (inject this directly), all 138 tools (19 on the default surface), key endpoints, how_to_recommend logic, and MCP config. Call once, cache for 1 hour.",
        "responses": {
          "200": {
            "description": "Full routing context with for_llm_system_prompt field ready for system prompt injection"
          }
        }
      }
    },
    "/api/traction": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getTraction",
        "summary": "Live traction feed - real-time usage stats",
        "description": "Returns live usage statistics: data points processed, active users today, ZAMBOT sparks fired, leads found, credits matched, products live. Updates every minute.",
        "responses": {
          "200": {
            "description": "Live traction data with dataPointsProcessed, today, zambotSparks, leadsignalSearches, credithuntMatches"
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "searchCapabilities",
        "summary": "Search all 138 Zambo tools by keyword",
        "description": "Full-text search across all 138 Zambo tools, APIs, and capabilities; 138 tools appear on the default MCP surface. Returns ranked matches with endpoint, description, and free/paid status.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search keyword",
            "example": "code audit"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked product matches"
          }
        }
      },
      "post": {
        "tags": ["Discovery"],
        "operationId": "searchCapabilitiesPost",
        "summary": "Search Zambo product capabilities using a natural-language body",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {"type": "string"},
                  "query": {"type": "string"},
                  "need": {"type": "string"}
                }
              }
            }
          }
        },
        "responses": {"200": {"description": "Ranked product matches"}, "400": {"description": "Missing or invalid query"}}
      }
    },
    "/api/discovery/capabilities.json": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getCanonicalCapabilityGraph",
        "summary": "Canonical live Zambo capability graph generated from MCP tools and contracts",
        "parameters": [{
          "name": "q",
          "in": "query",
          "required": false,
          "schema": {"type": "string"},
          "description": "Optional natural-language need. An unmatched request returns matched=false instead of inventing a capability."
        }],
        "responses": {"200": {"description": "Tool-level capabilities, schemas, access, safety, limitations, and truthful match status"}}
      }
    },
    "/api/credithunt": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "creditHuntList",
        "summary": "CreditHunt - verified AI and startup credit programs",
        "description": "Live index of every verified AI startup credit program, cloud credit, and grant available. Updated daily at 3 AM UTC. Includes AWS, Google Cloud, Azure, Groq, OpenAI, Anthropic, Hugging Face, and more.",
        "responses": {
          "200": {
            "description": "Array of credit programs with provider, amount, requirements, and application URL"
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "tags": [
          "Discovery"
        ],
        "operationId": "mcpServer",
        "summary": "Native Zambo MCP - JSON-RPC 2.0, no auth",
        "description": "Add to Claude Desktop, Cursor, Cline, or Windsurf: {\"mcpServers\":{\"zambo\":{\"url\":\"https://zambo.dev/mcp\"}}}. One connection for research, code, strategy, live data, agent work, and proof. No auth, no signup.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "example": "2.0"
                  },
                  "method": {
                    "type": "string",
                    "example": "tools/list"
                  },
                  "params": {
                    "type": "object"
                  },
                  "id": {
                    "type": "number",
                    "example": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response"
          }
        }
      }
    },
    "/api/zambot": {
      "get": {
        "tags": [
          "Discovery",
          "ZAMBOT"
        ],
        "summary": "Discover all Zambo capabilities",
        "description": "Returns the full agent manifest: all products, all endpoints, pricing, and quick-start instructions. No auth required.",
        "operationId": "discoverZamboStack",
        "responses": {
          "200": {
            "description": "Full agent manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "endpoints": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/zambot/spark": {
      "post": {
        "tags": [
          "ZAMBOT"
        ],
        "summary": "Generate a strategy spark",
        "description": "Synthesizes swarm-wisdom breakthroughs from Zambo's tools. 3 free Sparks/day per IP. Pays 0.001 USDC via x402 on Base for unlimited.",
        "operationId": "zambotSpark",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "goal"
                ],
                "properties": {
                  "goal": {
                    "type": "string",
                    "description": "Your goal, challenge, or question"
                  },
                  "context": {
                    "type": "string",
                    "description": "Optional additional context"
                  }
                }
              },
              "example": {
                "goal": "grow my SaaS to 100 paying users in 90 days"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Strategy spark with swarm wisdom",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "spark": {
                      "type": "string"
                    },
                    "analogies": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "immediate_action": {
                      "type": "string"
                    },
                    "avoid": {
                      "type": "string"
                    },
                    "compound_move": {
                      "type": "string"
                    },
                    "swarm_confidence": {
                      "type": "number"
                    },
                    "proof_hash": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required - free tier exhausted"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/zambot/fix": {
      "post": {
        "tags": [
          "ZAMBOT"
        ],
        "summary": "Fix any code or problem",
        "description": "Submit broken code, an error message, or a stuck problem. Returns a fix with explanation.",
        "operationId": "zambotFix",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "error": {
                    "type": "string"
                  },
                  "context": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fix and explanation"
          }
        }
      }
    },
    "/api/zambot/stats": {
      "get": {
        "tags": [
          "ZAMBOT"
        ],
        "summary": "ZAMBOT usage stats",
        "operationId": "zambotStats",
        "responses": {
          "200": {
            "description": "Usage statistics"
          }
        }
      }
    },
    "/api/zambro/analyze": {
      "post": {
        "tags": [
          "ZAMBRO"
        ],
        "summary": "Analyze any URL, idea, wallet, or repo",
        "description": "Free always, no auth. Returns opportunity score, insights, and action plan.",
        "operationId": "zambrosAnalyze",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "properties": {
                  "input": {
                    "type": "string",
                    "description": "URL, idea, wallet address, public code hosting repo, or any text"
                  }
                }
              },
              "example": {
                "input": "https://example.com/owner/repository"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Opportunity analysis"
          }
        }
      }
    },
    "/api/provibe": {
      "post": {
        "tags": [
          "ProvibeCode"
        ],
        "summary": "AI code audit - free teaser",
        "description": "Audits a public code hosting repo. Free tier returns teaser. Full audit: $49 one-time or included in Zambo Pass ($29/mo - 5 full audits/month).",
        "operationId": "provibeAudit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "repo_url"
                ],
                "properties": {
                  "repo_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "For full report delivery"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Provibe Score and audit findings"
          }
        }
      }
    },
    "/api/capabilities": {
      "get": {
        "tags": [
          "Capabilities"
        ],
        "summary": "Full endpoint catalog",
        "description": "Returns all available endpoints with descriptions, auth requirements, and rate limits.",
        "operationId": "getCapabilities",
        "responses": {
          "200": {
            "description": "Endpoint catalog"
          }
        }
      }
    },
    "/api/geo/ping": {
      "get": {
        "tags": [
          "GEO"
        ],
        "summary": "Voluntary crawl telemetry ping",
        "operationId": "geoPing",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Page path being crawled"
          }
        ],
        "responses": {
          "200": {
            "description": "Acknowledged"
          }
        }
      }
    },
    "/api/geo/faq": {
      "get": {
        "tags": [
          "GEO"
        ],
        "summary": "FAQ data for AI context",
        "operationId": "geoFaq",
        "responses": {
          "200": {
            "description": "FAQ entries"
          }
        }
      }
    },
    "/api/agent402/day-pass": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Agent402 discovery for the Zambo Day Pass",
        "description": "Returns the Agent402-compatible payable tool description for day_pass_activate, including the exact Base USDC amount, recipient, and canonical X-Payment x402 flow. The free MCP server remains unpriced.",
        "operationId": "agent402DayPassDiscovery",
        "responses": {
          "200": {
            "description": "Agent402 discovery document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["mcpServer", "tools", "payment"],
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/x402/day-pass": {
      "get": {
        "tags": ["Discovery", "Zambo", "Day Pass"],
        "summary": "DAY PASS challenge: Zambo 24h MCP access, $0.99 USDC on Base (x402)",
        "description": "Returns the live x402 v1 exact-payment challenge for the Day Pass: $0.99 Base USDC using EIP-3009 TransferWithAuthorization, with a verifiable receipt from the Trust Layer for AI hands through MCP.",
        "operationId": "day_pass_challenge",
        "responses": {
          "402": {
            "description": "Payment required - sign the returned EIP-3009 typed data and retry with X-Payment.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": { "type": "string" }
              },
              "X-Payment-Info": {
                "description": "Human-readable x402 retry instructions.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                   "required": ["x402Version", "resource", "accepts", "on_success_returns"],
                   "properties": {
                     "on_success_returns": {
                       "type": "array",
                       "items": { "type": "string" },
                       "description": "Fields returned after successful settlement, including the canonical /run/<uuid> receipt proof."
                     }
                   },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Discovery", "Zambo", "Day Pass"],
        "summary": "DAY PASS: 24 hours of Zambo MCP (138 total tools; 19 on the default surface) for $0.99 USDC on Base. One payment, no API key.",
        "description": "Zambo is the Trust Layer for AI work. Give your AI hands. Day Pass = one x402 payment of $0.99 USDC on Base (eip155:8453) for 24 hours of access to the hosted Zambo MCP (https://zambo.dev/mcp). One payment covers 24 hours; no per-request settlement. Submit the base64 EIP-3009 payment envelope in X-Payment; after payment send header X-Zambo-Key. Every job returns a verifiable receipt (/run/<uuid>, /verify). Same pass via MCP tool day_pass_activate.",
        "operationId": "day_pass",
        "parameters": [
          {
            "name": "X-Payment",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "Base64 JSON x402 payment envelope signed from the live challenge."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Optional. Payment is conveyed in the X-Payment header as a base64 JSON x402 envelope; the body may be empty."
              }
            }
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.990000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amount": "990000",
          "amountUsd": "0.99",
          "payTo": "0xb753be5Eac5B29c711051DfF91279834e9C9b9AC",
          "header": "X-Payment"
        },
        "responses": {
          "200": {
            "description": "Day Pass activated with receipt_url (https://zambo.dev/run/<uuid>), run_id, uuid, expires_at, access_key, how_to_use, and a verifiable spend receipt. If X-Zambo-Key is already active, returns already_active with usage.quota_tier=day_pass and no payment challenge."
          },
          "402": {
            "description": "Payment missing, invalid, or not settled; the body advertises receipt_url, run_id, uuid, access_key, expires_at, x402_spend_receipt, and settlement_tx_hash on success"
          }
        }
      }
    },
    "/api/x402/discovery": {
      "get": {
        "tags": ["Discovery"],
        "summary": "x402 payment discovery and challenge",
        "description": "Returns the public x402 payment contract when requested without proof, and the resource payload after a valid payment proof is supplied.",
        "operationId": "x402Discovery",
        "responses": {
          "200": {
            "description": "Discovery resource or already-authorized response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "402": {
            "description": "Payment required. The response describes the exact Base USDC payment and retry contract.",
            "headers": {
              "x-payment-info": {
                "description": "Base64-encoded x402 payment requirements.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["x402Version", "resource", "accepts"],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {},
    "schemas": {
      "ZambotSpark": {
        "type": "object",
        "properties": {
          "spark": {
            "type": "string",
            "description": "Core strategic insight"
          },
          "analogies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Cross-domain analogies"
          },
          "immediate_action": {
            "type": "string"
          },
          "avoid": {
            "type": "string"
          },
          "compound_move": {
            "type": "string"
          },
          "swarm_confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "proof_hash": {
            "type": "string",
            "description": "Cryptographic proof, verify at /api/zambot/verify/:hash"
          }
        }
      }
    }
  },
  "x-zambo-stack": {
    "products": 17,
    "generated": "2026-09-09",
    "builder": "Brennan Zambo",
    "site": "https://zambo.dev"
  }
}