{
  "openapi": "3.1.0",
  "info": {
    "title": "BuzzMeBro agent API",
    "version": "1.0.0",
    "description": "BuzzMeBro gives an apartment its own local phone number so the building’s lobby buzzer rings every roommate’s phone at once; whoever answers presses the usual digit to open the door. It is for renters and condo residents in Canada (Toronto/GTA and Greater Vancouver first).\n\nUse these tools when your user wants their apartment buzzer to ring more than one phone, needs a buzzer number because they have no landline, is moving in with roommates, or asks you to buy or set up BuzzMeBro for them.\n\nOrder: 1) check_building with their postal code. 2) If available, ask for their unit number and mobile number and call create_setup. 3) Give them the setup_url (or the ready message_for_the_person). They type the code we text them and add a card on Stripe’s page; you cannot do those two steps for them. If you control a browser you may open the link with them. 4) Call get_setup_status until status is \"ready\", then give them their BuzzMeBro number and walk them through swap_the_buzzer, offering to send the building message for them.\n\nNever invent prices, promises or availability: quote only what these tools return.",
    "contact": {
      "email": "support@buzzmebro.com",
      "url": "https://buzzmebro.com/agents"
    },
    "termsOfService": "https://buzzmebro.com/terms"
  },
  "servers": [
    {
      "url": "https://buzzmebro.com/api/agent/v1"
    }
  ],
  "paths": {
    "/check": {
      "post": {
        "operationId": "checkBuilding",
        "summary": "Check a building",
        "description": "Checks whether BuzzMeBro can give this building a local buzzer number, and returns the price, the free-trial terms and how the service works. Call this first. Stores nothing and costs nothing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postal_code": {
                    "type": "string",
                    "description": "The apartment building’s postal code, e.g. \"M4B 1B3\". Canadian postal codes only for now.",
                    "minLength": 3,
                    "maxLength": 12
                  }
                },
                "required": [
                  "postal_code"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Availability, price and how it works.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "description": "Slow down.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/setups": {
      "post": {
        "operationId": "createSetup",
        "summary": "Set up BuzzMeBro for the person",
        "description": "Creates a pre-filled BuzzMeBro setup for the person and returns setup_url, the one link they open to finish, plus a status_token you must keep to call get_setup_status. Only call it after check_building said available and the person has asked you to set it up. No text message is sent and nothing is charged by this call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postal_code": {
                    "type": "string",
                    "description": "The apartment building’s postal code, e.g. \"M4B 1B3\". Canadian postal codes only for now.",
                    "minLength": 3,
                    "maxLength": 12
                  },
                  "unit": {
                    "type": "string",
                    "description": "Their apartment or unit number as the lobby panel lists it, e.g. \"1502\", \"B\" or \"PH3\".",
                    "minLength": 1,
                    "maxLength": 32
                  },
                  "mobile_phone": {
                    "type": "string",
                    "description": "The person’s own mobile number. It becomes the first phone the buzzer rings and how they sign in; we text it a code when they open the link.",
                    "minLength": 7,
                    "maxLength": 32
                  },
                  "referral_code": {
                    "type": "string",
                    "description": "Optional BuzzMeBro referral code from a friend.",
                    "maxLength": 20
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "Optional: your name as the person knows you (e.g. \"ChatGPT\", \"Claude\"), shown on their link page.",
                    "maxLength": 64
                  }
                },
                "required": [
                  "postal_code",
                  "unit",
                  "mobile_phone"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "setup_id, setup_url for the person, status_token for you.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "We cannot serve this building yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "description": "Slow down.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/setups/{setup_id}": {
      "get": {
        "operationId": "getSetupStatus",
        "summary": "Check setup progress",
        "description": "Reads how far the person has got. When status is \"ready\" it returns their new BuzzMeBro number and swap_the_buzzer: the steps to get the building to point the buzzer at that number, and ready-to-send messages for building management, the landlord, the concierge, the superintendent or a building portal. Send the status_token as \"Authorization: Bearer <status_token>\".",
        "parameters": [
          {
            "name": "setup_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "statusToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Progress, and the number and building messages once ready.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Unknown id or token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "statusToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "status_token from createSetup."
      }
    }
  },
  "x-mcp-server": "https://buzzmebro.com/api/mcp"
}