{
  "openapi": "3.1.0",
  "info": {
    "title": "BotPlaza API",
    "version": "1.0.0",
    "description": "Search, read and install BotPlaza skills and bundles. Read-only, no key needed, CORS open. Same data as the MCP server at https://botplaza.lol/api/mcp.",
    "contact": {
      "url": "https://botplaza.lol/"
    }
  },
  "servers": [
    {
      "url": "https://botplaza.lol"
    }
  ],
  "externalDocs": {
    "description": "llms.txt",
    "url": "https://botplaza.lol/llms.txt"
  },
  "paths": {
    "/api/skills": {
      "get": {
        "operationId": "listSkills",
        "summary": "List or search skills",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search words.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Agent to install on. grok (Grok Bot), muse, dots, or generic for any assistant.",
            "schema": {
              "type": "string",
              "enum": [
                "grok",
                "grokBot",
                "muse",
                "dots",
                "generic"
              ],
              "default": "grok"
            }
          },
          {
            "name": "audience",
            "in": "query",
            "required": false,
            "description": "bots for skills written for agents, people for the rest.",
            "schema": {
              "type": "string",
              "enum": [
                "bots",
                "people"
              ]
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category name (list only).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching skills",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillList"
                }
              }
            }
          }
        }
      }
    },
    "/api/skills/{slug}": {
      "get": {
        "operationId": "getSkill",
        "summary": "One skill with its install prompt",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Skill slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Agent to install on. grok (Grok Bot), muse, dots, or generic for any assistant.",
            "schema": {
              "type": "string",
              "enum": [
                "grok",
                "grokBot",
                "muse",
                "dots",
                "generic"
              ],
              "default": "grok"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The skill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Skill"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/skill": {
      "get": {
        "operationId": "getSkillByQuery",
        "summary": "One skill (query form of /api/skills/{slug})",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "description": "Skill slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Agent to install on. grok (Grok Bot), muse, dots, or generic for any assistant.",
            "schema": {
              "type": "string",
              "enum": [
                "grok",
                "grokBot",
                "muse",
                "dots",
                "generic"
              ],
              "default": "grok"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The skill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Skill"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/install": {
      "get": {
        "operationId": "installSkill",
        "summary": "Install kit: prompt, SKILL.md, schedule, setup questions and safety notes",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "description": "Skill slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Agent to install on. grok (Grok Bot), muse, dots, or generic for any assistant.",
            "schema": {
              "type": "string",
              "enum": [
                "grok",
                "grokBot",
                "muse",
                "dots",
                "generic"
              ],
              "default": "grok"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Install kit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallKit"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/bundles": {
      "get": {
        "operationId": "listBundles",
        "summary": "List bundles and teams",
        "responses": {
          "200": {
            "description": "Bundles and teams",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BundleList"
                }
              }
            }
          }
        }
      }
    },
    "/api/bundles/{id}": {
      "get": {
        "operationId": "getBundle",
        "summary": "One bundle or team with members, setup and its install prompt",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Bundle or team id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Agent to install on. grok (Grok Bot), muse, dots, or generic for any assistant.",
            "schema": {
              "type": "string",
              "enum": [
                "grok",
                "grokBot",
                "muse",
                "dots",
                "generic"
              ],
              "default": "grok"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The bundle",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bundle"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/bundles/{id}/install": {
      "get": {
        "operationId": "installBundle",
        "summary": "The one prompt that installs the whole bundle",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Bundle or team id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Agent to install on. grok (Grok Bot), muse, dots, or generic for any assistant.",
            "schema": {
              "type": "string",
              "enum": [
                "grok",
                "grokBot",
                "muse",
                "dots",
                "generic"
              ],
              "default": "grok"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bundle install kit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bundle"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "SkillBrief": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "audience": {
            "type": "string",
            "enum": [
              "bots",
              "people"
            ]
          },
          "schedule": {
            "type": [
              "string",
              "null"
            ]
          },
          "costLevel": {
            "type": [
              "string",
              "null"
            ]
          },
          "writesOrSends": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "slug",
          "name"
        ]
      },
      "SkillList": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "query": {
            "type": "object"
          },
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkillBrief"
            }
          }
        }
      },
      "Skill": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "schedule": {
            "type": [
              "string",
              "null"
            ]
          },
          "installPrompt": {
            "type": "string"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "safety": {
            "type": [
              "object",
              "null"
            ]
          },
          "dataSources": {
            "type": "array"
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "InstallKit": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "skillMd": {
            "type": [
              "string",
              "null"
            ]
          },
          "prompt": {
            "type": "string"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "schedule": {
            "type": [
              "string",
              "null"
            ]
          },
          "setup": {
            "type": "array",
            "description": "Setup questions to ask once."
          },
          "safety": {
            "type": [
              "object",
              "null"
            ]
          },
          "dataSources": {
            "type": "array"
          },
          "urls": {
            "type": "object"
          },
          "next": {
            "type": "string"
          }
        }
      },
      "BundleBrief": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "bundle",
              "team"
            ]
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "members": {
            "type": "array"
          },
          "costLevel": {
            "type": [
              "string",
              "null"
            ]
          },
          "urls": {
            "type": "object"
          }
        }
      },
      "BundleList": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "bundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BundleBrief"
            }
          }
        }
      },
      "Bundle": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "members": {
            "type": "array"
          },
          "safety": {
            "type": [
              "object",
              "null"
            ]
          },
          "urls": {
            "type": "object"
          }
        }
      }
    }
  }
}