{
  "openapi": "3.1.0",
  "info": {
    "title": "That Marketing Buddy API",
    "version": "1.0.0",
    "summary": "Read-only API for marketing software data: pricing, ratings, MCP/API capability flags, and category rankings.",
    "description": "That Marketing Buddy reviews and scores marketing software for AI-stack fit (MCP support, API access, agent-readiness) and publishes pricing verified against the vendor. This API exposes the same published data programmatically. It is public and unauthenticated: every field returned here is already visible on the corresponding thatmarketingbuddy.com page. Use it to look up current pricing for a specific tool, check whether a tool has an MCP server or public API, or pull a category's tools ranked by price.",
    "contact": {
      "name": "That Marketing Buddy",
      "url": "https://thatmarketingbuddy.com/contact",
      "email": "hello@thatmarketingbuddy.com"
    }
  },
  "servers": [
    { "url": "https://thatmarketingbuddy.com/api/v1", "description": "Production" }
  ],
  "paths": {
    "/software": {
      "get": {
        "operationId": "listSoftware",
        "summary": "List marketing software",
        "description": "Returns published marketing tools, optionally filtered by category. Paginated. Use this to enumerate every tool covered by the site, or every tool in one category, before fetching a single tool's full detail.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug to filter by (see GET /categories for valid values).",
            "schema": { "type": "string", "example": "email-marketing-software" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results to return, 1-100.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of results to skip, for pagination.",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of software summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/SoftwareSummary" } },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "offset": { "type": "integer" },
                        "category": { "type": ["string", "null"] }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid `limit` or `offset`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/software/{slug}": {
      "get": {
        "operationId": "getSoftware",
        "summary": "Get one tool's full detail",
        "description": "Returns pricing plans, ratings, pros/cons, and MCP/API/Zapier/Make capability flags for one tool, verified against the vendor. Use this after listSoftware to get full detail on a specific tool, or directly if you already know the slug.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Tool slug, e.g. \"activecampaign\", \"kit\", \"semrush\".",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Full tool detail.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": { "data": { "$ref": "#/components/schemas/SoftwareDetail" } }
                }
              }
            }
          },
          "404": {
            "description": "No tool with that slug.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List software categories",
        "description": "Returns every category with at least two tools, its tool count, MCP-ready count, and current top tool. Use this to discover valid category slugs before calling listSoftware?category= or getBestInCategory.",
        "responses": {
          "200": {
            "description": "All categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } },
                    "meta": { "type": "object", "properties": { "total": { "type": "integer" } } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/best/{categorySlug}": {
      "get": {
        "operationId": "getBestInCategory",
        "summary": "Rank a category's tools by price",
        "description": "Returns every tool in a category, sorted cheapest paid plan first. This is a price ranking, not the site's editorial \"best of\" pick order (which also weighs MCP/API support and agent-readiness) — check `meta.ranking` in the response, which is always \"price-ascending\" today.",
        "parameters": [
          {
            "name": "categorySlug",
            "in": "path",
            "required": true,
            "description": "Category slug, e.g. \"seo-software\" (see GET /categories for valid values).",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Tools in the category, cheapest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankedTool" } },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "category": { "type": "string" },
                        "total": { "type": "integer" },
                        "ranking": { "type": "string", "enum": ["price-ascending"] }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No tools found for that category slug.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SoftwareSummary": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "shortDescription": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "websiteUrl": { "type": "string", "format": "uri" },
          "rating": { "type": ["number", "null"] },
          "hasFreePlan": { "type": "boolean" },
          "hasMcpServer": { "type": "boolean" },
          "hasApi": { "type": "boolean" },
          "categories": { "type": "array", "items": { "type": "string" } }
        }
      },
      "SoftwareDetail": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "shortDescription": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "websiteUrl": { "type": "string", "format": "uri" },
          "logoUrl": { "type": ["string", "null"], "format": "uri" },
          "rating": { "type": ["number", "null"] },
          "hasFreePlan": { "type": "boolean" },
          "freeTrialDays": { "type": ["integer", "null"] },
          "moneyBackDays": { "type": ["integer", "null"] },
          "lowestPaidPrice": { "type": ["number", "null"] },
          "pricingPlans": { "type": "array", "items": { "type": "object" } },
          "hasApi": { "type": "boolean" },
          "hasMcpServer": { "type": "boolean" },
          "hasZapier": { "type": "boolean" },
          "hasMake": { "type": "boolean" },
          "pros": { "type": "array", "items": { "type": "string" } },
          "cons": { "type": "array", "items": { "type": "string" } },
          "pricingLastVerified": { "type": ["string", "null"], "format": "date" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "toolCount": { "type": "integer" },
          "mcpReadyCount": { "type": "integer" },
          "topTool": {
            "type": ["object", "null"],
            "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }
          },
          "bestListUrl": { "type": "string", "format": "uri" }
        }
      },
      "RankedTool": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "lowestPrice": { "type": ["number", "null"] },
          "hasFreePlan": { "type": "boolean" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string", "example": "software_not_found" },
              "message": { "type": "string" },
              "hint": { "type": "string" }
            }
          }
        }
      }
    }
  }
}