{
  "openapi": "3.1.0",
  "info": {
    "title": "Waspes Public Discovery & MCP Agent API",
    "version": "1.0.0",
    "description": "Public REST & Model Context Protocol (MCP) API for Waspes (https://waspes.com) — AI Website Builder, 3D Studio & Agent Platform.\n\n### Versioning & Deprecation Policy\nAll endpoints support URL path versioning (`/api/v1/mcp`) and the `X-API-Version` header (current version: `2026-10-24`). Deprecated endpoints emit standard RFC `Deprecation` and `Sunset` HTTP response headers at least 90 days before removal.\n\n### Rate Limiting\nResponses include standard `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers (60 requests/minute default). When rate-limited, the API returns HTTP `429 Too Many Requests` with a `Retry-After` header and a structured `ErrorResponse` JSON body.",
    "contact": {
      "name": "Waspes API & Developer Support",
      "url": "https://waspes.com/developers",
      "email": "hello@waspes.com"
    },
    "license": {
      "name": "Commercial / Waspes Terms of Service",
      "url": "https://waspes.com/terms"
    },
    "x-deprecation-policy": {
      "sunsetNoticeDays": 90,
      "headers": [
        "Deprecation",
        "Sunset",
        "Link"
      ],
      "policyUrl": "https://waspes.com/developers#versioning"
    }
  },
  "servers": [
    {
      "url": "https://waspes.com",
      "description": "Waspes Production API (v1)"
    },
    {
      "url": "https://waspes.com/api/v1",
      "description": "Waspes Versioned API Base (/api/v1)"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "APIKey",
        "description": "Waspes API key (`wsp_live_...`) or OAuth 2.1 access token."
      }
    },
    "parameters": {
      "ApiVersionHeader": {
        "name": "X-API-Version",
        "in": "header",
        "required": false,
        "description": "Optional API version pin (e.g. `2026-10-24`).",
        "schema": {
          "type": "string",
          "default": "2026-10-24"
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "RFC 9457 problem type URI.",
            "example": "https://waspes.com/developers#errors"
          },
          "title": {
            "type": "string",
            "description": "Short human-readable summary of the problem type.",
            "example": "Invalid Request"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "example": "invalid_request"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description.",
            "example": "The request body must be a valid JSON-RPC 2.0 payload."
          },
          "detail": {
            "type": "string",
            "description": "Detailed explanation of the error."
          },
          "resolution": {
            "type": "string",
            "description": "Actionable hint for resolving the error.",
            "example": "Consult https://waspes.com/developers or pass a valid JSON-RPC 2.0 request."
          }
        }
      },
      "McpServerInfoResponse": {
        "type": "object",
        "required": [
          "name",
          "version",
          "protocolVersion",
          "endpoint",
          "tools"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Waspes"
          },
          "title": {
            "type": "string",
            "example": "Waspes"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "description": {
            "type": "string"
          },
          "websiteUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://waspes.com"
          },
          "protocolVersion": {
            "type": "string",
            "example": "2025-06-18"
          },
          "endpoint": {
            "type": "string",
            "format": "uri",
            "example": "https://waspes.com/api/mcp"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "description"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "McpRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ],
            "default": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "method": {
            "type": "string",
            "description": "MCP JSON-RPC method (e.g. initialize, tools/list, tools/call, resources/list, resources/read).",
            "example": "tools/list"
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "Method parameters."
          }
        }
      },
      "McpRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "description": "JSON-RPC result object on success."
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "example": -32602
              },
              "message": {
                "type": "string",
                "example": "Invalid params"
              },
              "data": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "MarkdownDocumentResponse": {
        "type": "string",
        "description": "UTF-8 Markdown document."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request — invalid parameters or malformed payload.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          },
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized — missing or invalid Waspes API key (`wsp_live_...`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          },
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests — rate limit exceeded.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "example": 60
            }
          },
          "RateLimit-Limit": {
            "description": "Request limit per minute.",
            "schema": {
              "type": "integer",
              "example": 60
            }
          },
          "RateLimit-Remaining": {
            "description": "Remaining requests in the current window.",
            "schema": {
              "type": "integer",
              "example": 0
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          },
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal Server Error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          },
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/mcp": {
      "get": {
        "operationId": "getMcpServerInfoV1",
        "summary": "Get versioned Waspes MCP Server metadata and tool catalog (v1)",
        "description": "Returns the Waspes MCP server identity, protocol version, and tool definitions.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersionHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "JSON metadata describing the Waspes MCP server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpServerInfoResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "operationId": "invokeMcpRpcV1",
        "summary": "Execute a versioned JSON-RPC 2.0 Model Context Protocol request (v1)",
        "description": "Invoke MCP methods (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`).",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersionHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpRpcResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "getMcpServerInfo",
        "summary": "Get Waspes MCP Server discovery metadata and tool list",
        "description": "Returns JSON metadata describing the Waspes MCP server and all available tools.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersionHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "JSON metadata describing the Waspes MCP server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpServerInfoResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "operationId": "invokeMcpRpc",
        "summary": "Execute a JSON-RPC 2.0 Model Context Protocol request",
        "description": "Streamable HTTP MCP endpoint supporting `initialize`, `tools/list`, `tools/call`, `resources/list`, and `resources/read`.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersionHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpRpcResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Get concise LLM & AI agent instructions for Waspes",
        "description": "Returns the canonical llms.txt Markdown overview for AI agents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersionHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown summary for LLMs and AI agents.",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocumentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/pricing.md": {
      "get": {
        "operationId": "getPricingMarkdown",
        "summary": "Get Waspes pricing plans and credit breakdown in Markdown",
        "description": "Returns machine-readable pricing tables for all 5 Waspes plans.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersionHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown pricing reference.",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocumentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  }
}