{
  "openapi": "3.1.0",
  "info": {
    "title": "Minoa public content API",
    "version": "1.0.0",
    "summary": "Read-only access to Minoa's public marketing content.",
    "description": "Minoa is the value intelligence layer for B2B revenue teams. This API exposes the public content on www.minoa.io (company profile, pricing, articles, and the value selling glossary) as JSON, so agents can read it without scraping HTML. It requires no authentication and never mutates data. The Minoa product API and the Minoa MCP server are documented separately at https://docs.minoa.io and https://mcp.minoa.io.",
    "contact": {
      "name": "Minoa",
      "url": "https://www.minoa.io/contact",
      "email": "hello@minoa.io"
    },
    "license": {
      "name": "Minoa Terms of Service",
      "url": "https://www.minoa.io/legal/gtc"
    },
    "termsOfService": "https://www.minoa.io/legal/gtc"
  },
  "servers": [
    {
      "url": "https://www.minoa.io",
      "description": "Production"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Minoa developer resources",
    "url": "https://www.minoa.io/developers"
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "Endpoint index and machine-readable descriptions."
    },
    {
      "name": "Company",
      "description": "Company profile and contact details."
    },
    {
      "name": "Pricing",
      "description": "Published plans and billing model."
    },
    {
      "name": "Content",
      "description": "Articles and glossary terms."
    },
    {
      "name": "Forms",
      "description": "Public form submissions on www.minoa.io."
    }
  ],
  "paths": {
    "/server.json": {
      "get": {
        "operationId": "getMcpServerManifest",
        "tags": [
          "Discovery"
        ],
        "summary": "Describe the Minoa MCP server",
        "description": "Returns the Minoa MCP server manifest in the official server.json format, naming the remote endpoint and its transport. The MCP server itself authenticates every call, so this manifest is the public description of it. It is also the document published to registry.modelcontextprotocol.io.",
        "responses": {
          "200": {
            "description": "The MCP server manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "description",
                    "version",
                    "remotes"
                  ],
                  "properties": {
                    "$schema": {
                      "type": "string",
                      "format": "uri"
                    },
                    "name": {
                      "type": "string",
                      "description": "Registry name, in reverse-DNS namespace form.",
                      "examples": [
                        "io.minoa/minoa"
                      ]
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "websiteUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "remotes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "type",
                          "url"
                        ],
                        "properties": {
                          "type": {
                            "type": "string",
                            "examples": [
                              "streamable-http"
                            ]
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "operationId": "getApiIndex",
        "tags": [
          "Discovery"
        ],
        "summary": "List the public API endpoints",
        "description": "Returns the endpoint index for the Minoa public content API, plus pointers to the OpenAPI description, the product documentation, and the Minoa MCP server.",
        "responses": {
          "200": {
            "description": "The endpoint index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "version",
                    "endpoints"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "openapi_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "documentation_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "product_documentation_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "mcp_server_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "mcp_manifest_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "llms_txt_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "endpoints": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "operation_id",
                          "method",
                          "path"
                        ],
                        "properties": {
                          "operation_id": {
                            "type": "string"
                          },
                          "method": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/company": {
      "get": {
        "operationId": "getCompany",
        "tags": [
          "Company"
        ],
        "summary": "Get the Minoa company profile",
        "description": "Returns the legal entity, postal address, founders, contact channels, and canonical links for Minoa. Use this to verify the business or to route a contact request.",
        "responses": {
          "200": {
            "description": "The company profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "legal_name",
                    "url",
                    "email",
                    "address"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "legal_name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "founding_date": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "logo_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "email": {
                      "type": "string",
                      "format": "email"
                    },
                    "address": {
                      "type": "object",
                      "required": [
                        "street_address",
                        "locality",
                        "country"
                      ],
                      "properties": {
                        "street_address": {
                          "type": "string"
                        },
                        "locality": {
                          "type": "string"
                        },
                        "region": {
                          "type": "string"
                        },
                        "postal_code": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string",
                          "description": "ISO 3166-1 alpha-2 country code."
                        },
                        "formatted": {
                          "type": "string"
                        }
                      }
                    },
                    "founders": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "job_title": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "contact": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "format": "uri"
                      }
                    },
                    "links": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pricing": {
      "get": {
        "operationId": "getPricing",
        "tags": [
          "Pricing"
        ],
        "summary": "Get published pricing plans",
        "description": "Returns Minoa's published plans with the flat annual platform fee, seat range, and what each plan includes, plus the pricing FAQ. Prices are in USD.",
        "responses": {
          "200": {
            "description": "The published pricing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "plans",
                    "currency"
                  ],
                  "properties": {
                    "summary": {
                      "type": "string"
                    },
                    "currency": {
                      "type": "string",
                      "examples": [
                        "USD"
                      ]
                    },
                    "billing_model": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "plans": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "seat_range"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "enum": [
                              "starter",
                              "growth",
                              "enterprise"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "tagline": {
                            "type": "string"
                          },
                          "annual_platform_fee": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Flat annual platform fee in USD, before AI capacity."
                          },
                          "price_prefix": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "examples": [
                              "Starting at"
                            ]
                          },
                          "seat_range": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cta_url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "faq": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "question": {
                            "type": "string"
                          },
                          "answer": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts": {
      "get": {
        "operationId": "listPosts",
        "tags": [
          "Content"
        ],
        "summary": "List published articles",
        "description": "Returns published articles, customer stories, product updates, and guides, newest first. Bodies are omitted; fetch a single post for its Markdown.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Case-insensitive editorial category filter.",
            "schema": {
              "type": "string",
              "examples": [
                "Articles",
                "Customer Stories",
                "Product Updates",
                "Engineering"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of posts to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of posts to skip, for paging.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of posts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "total",
                    "posts"
                  ],
                  "properties": {
                    "total": {
                      "type": "integer",
                      "description": "Total posts matching the filter."
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PostSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The limit or offset parameter is not a valid integer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts/{slug}": {
      "get": {
        "operationId": "getPost",
        "tags": [
          "Content"
        ],
        "summary": "Get a single article with its Markdown body",
        "description": "Returns one article including the full Markdown body, so an agent can quote or summarize it without parsing the page HTML.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The post slug, as returned by listPosts.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The article.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "404": {
            "description": "No published post matches the slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/glossary": {
      "get": {
        "operationId": "listGlossaryTerms",
        "tags": [
          "Content"
        ],
        "summary": "List value selling glossary terms",
        "description": "Returns every term in Minoa's value selling glossary, alphabetically. Bodies are omitted; fetch a single term for its Markdown definition.",
        "responses": {
          "200": {
            "description": "Every glossary term.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "total",
                    "terms"
                  ],
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "terms": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GlossaryTermSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/glossary/{slug}": {
      "get": {
        "operationId": "getGlossaryTerm",
        "tags": [
          "Content"
        ],
        "summary": "Get a single glossary term with its Markdown definition",
        "description": "Returns one glossary term including the full Markdown definition.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The term slug, as returned by listGlossaryTerms.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The glossary term.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTerm"
                }
              }
            }
          },
          "404": {
            "description": "No glossary term matches the slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/md/{path}": {
      "get": {
        "operationId": "getPageAsMarkdown",
        "tags": [
          "Content"
        ],
        "summary": "Get any public page as Markdown",
        "description": "Returns the Markdown rendering of a public page on www.minoa.io. Requesting the page itself with the header `Accept: text/markdown` returns the same body, so agents can read any URL as Markdown without a separate path.",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "The page path without a leading slash, for example `resources/blog/automating-the-business-case`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page as Markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No public page matches the path.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/demo-request": {
      "post": {
        "operationId": "validateDemoRequest",
        "tags": [
          "Forms"
        ],
        "summary": "Validate a demo request before booking",
        "description": "Validates the name and email a visitor entered on https://www.minoa.io/demo before the booking calendar opens. It does not create a booking; agents should send people to the demo page instead.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "_website": {
                    "type": "string",
                    "description": "Honeypot field; leave empty."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The submission was accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "proceed": {
                      "type": "boolean",
                      "description": "Whether the booking calendar should open."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The name or email failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "error"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": false
                    },
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts POST.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/report-download": {
      "post": {
        "operationId": "requestReportDownload",
        "tags": [
          "Forms"
        ],
        "summary": "Request the State of B2B Buying Behavior report",
        "description": "Exchanges an email address for the download URL of Minoa's 2026 data report, The Audience of One.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "referrer": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "_website": {
                    "type": "string",
                    "description": "Honeypot field; leave empty."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The download URL.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "downloadUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The email failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "error"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": false
                    },
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "This endpoint only accepts POST.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "resolution",
              "status"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable identifier for the failure.",
                "examples": [
                  "not_found",
                  "invalid_parameter",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of what went wrong."
              },
              "resolution": {
                "type": "string",
                "description": "What the caller should do next."
              },
              "status": {
                "type": "integer",
                "description": "HTTP status code, repeated in the body."
              },
              "documentation_url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "PostSummary": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "description",
          "date",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "URL-safe identifier for the post."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Publication date, ISO 8601."
          },
          "last_updated": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Editorial category.",
            "examples": [
              "Articles",
              "Customer Stories",
              "Product Updates",
              "Engineering"
            ]
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical page for the post."
          },
          "api_url": {
            "type": "string",
            "format": "uri",
            "description": "This API's URL for the full post."
          }
        }
      },
      "Post": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PostSummary"
          },
          {
            "type": "object",
            "required": [
              "content"
            ],
            "properties": {
              "content_format": {
                "type": "string",
                "const": "markdown"
              },
              "content": {
                "type": "string",
                "description": "The full body as Markdown."
              }
            }
          }
        ]
      },
      "GlossaryTermSummary": {
        "type": "object",
        "required": [
          "slug",
          "term",
          "title",
          "description",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "term": {
            "type": "string",
            "description": "The term as written in prose."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "related_terms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "api_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "GlossaryTerm": {
        "allOf": [
          {
            "$ref": "#/components/schemas/GlossaryTermSummary"
          },
          {
            "type": "object",
            "required": [
              "content"
            ],
            "properties": {
              "content_format": {
                "type": "string",
                "const": "markdown"
              },
              "content": {
                "type": "string",
                "description": "The full body as Markdown."
              }
            }
          }
        ]
      }
    }
  }
}