{
  "openapi": "3.1.0",
  "info": {
    "title": "Beaam API",
    "version": "2026-10-08",
    "summary": "Every Beaam capability — 131 operations, one endpoint shape, one envelope.",
    "description": "Generated from the production capability manifest on 2026-10-08. The same manifest drives the MCP connector, so an operation here behaves identically there.\n\nEvery operation is `POST /api/v1/{capability}` with the input as the JSON body.\n\n**Responses share one envelope.** Success is `{ \"ok\": true, \"data\": … }`. A failed *request* is `{ \"ok\": false, \"error\": \"…\" }` — `error` is a string, ready to show. The HTTP status carries the class: 400 invalid input, 401 no or bad credential, 404 unknown capability, 413 body too large, 429 rate limited (`retry-after` is set), 500 the capability failed.\n\n**A refused operation is a 200, not an error.** A plan limit, a credential the provider rejected, an expired invitation: these come back `200 { ok: true, data: { status: \"error\", message } }`. Check, in order: the HTTP status, then `ok`, then `data.status`.\n\nFull conventions: https://beaam.app/docs/conventions/",
    "termsOfService": "https://app.beaam.app/tos",
    "contact": {
      "name": "Beaam support",
      "email": "support@beaam.app",
      "url": "https://beaam.app/docs/api/"
    },
    "x-manifest-synced-at": "2026-10-08"
  },
  "servers": [
    {
      "url": "https://app.beaam.app",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "status",
      "description": "Current health, incidents, and the public status page."
    },
    {
      "name": "integrations",
      "description": "Connect providers, choose what is watched, and tune thresholds."
    },
    {
      "name": "history",
      "description": "Past incidents, alerts sent, and detection statistics."
    },
    {
      "name": "account",
      "description": "Profile, organizations, notification channels, API keys, and billing."
    }
  ],
  "paths": {
    "/api/v1/accept-invitation": {
      "post": {
        "operationId": "acceptInvitation",
        "summary": "Accept an invitation",
        "description": "Accept an organization invitation using its token. Joins the org and makes it your active organization.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The invitation token from the accept link."
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": false
              },
              "example": {
                "token": "replace_with_token"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "orgId": {
                          "type": "string"
                        },
                        "orgName": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "orgId": "00000000-0000-4000-8000-000000000000",
                        "orgName": "<orgName>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "accept-invitation",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/acknowledge-welcome": {
      "post": {
        "operationId": "acknowledgeWelcome",
        "summary": "Acknowledge the welcome",
        "description": "Record that this account has seen its welcome message, so it is shown once and never again.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "welcomedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "firstTime": {
                          "type": "boolean",
                          "description": "True if this call is what marked the account as welcomed."
                        }
                      },
                      "required": [
                        "welcomedAt",
                        "firstTime"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "welcomedAt": "2026-01-01T00:00:00.000Z",
                        "firstTime": false
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "acknowledge-welcome",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/cancel-maintenance-window": {
      "post": {
        "operationId": "cancelMaintenanceWindow",
        "summary": "Cancel a maintenance window",
        "description": "Remove a planned quiet period so alerts resume. Cancelling an active window restores alerting immediately.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "windowId": {
                    "type": "string",
                    "description": "The window to cancel."
                  }
                },
                "required": [
                  "windowId"
                ],
                "additionalProperties": false
              },
              "example": {
                "windowId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "windowId": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "windowId": "00000000-0000-4000-8000-000000000000",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "cancel-maintenance-window",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/cancel-subscription": {
      "post": {
        "operationId": "cancelSubscription",
        "summary": "Cancel subscription",
        "description": "Cancel the caller's Solo subscription at the end of the current billing period (downgrade to Free). Access continues until period end.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "cancel-subscription",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/create-api-key": {
      "post": {
        "operationId": "createApiKey",
        "summary": "Create an API key",
        "description": "Create a personal API key for the public API and the hosted MCP server. The secret is shown once at creation.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "A label to recognise this key, e.g. 'Claude MCP'."
                  },
                  "expiresInDays": {
                    "type": "integer",
                    "description": "Days until the key expires. Omit or 0 for a key that never expires."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "replace_with_name",
                "expiresInDays": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "prefix": {
                          "type": "string"
                        },
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "key": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "id": "00000000-0000-4000-8000-000000000000",
                        "name": "<name>",
                        "prefix": "<prefix>",
                        "expiresAt": "2026-01-01T00:00:00.000Z",
                        "key": "<key>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "create-api-key",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/create-checkout": {
      "post": {
        "operationId": "createCheckout",
        "summary": "Start Solo checkout",
        "description": "Create a secure Polar checkout session for the signed-in Beaam account's $19/month Solo plan.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entryPoint": {
                    "type": "string",
                    "description": "Optional label for where the upgrade was started (e.g. integrations_hub, sidebar_meter)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "entryPoint": "replace_with_entry_point"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "url": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "url": "https://example.com",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "create-checkout",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/create-organization": {
      "post": {
        "operationId": "createOrganization",
        "summary": "Create an organization",
        "description": "Create a new organization (a separate workspace with its own integrations, members, and plan) and switch to it.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "A name for the new organization."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "replace_with_name"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "id": "00000000-0000-4000-8000-000000000000",
                        "name": "<name>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "create-organization",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/delete-account": {
      "post": {
        "operationId": "deleteAccount",
        "summary": "Delete account",
        "description": "Permanently delete your Beaam account and associated monitoring data after password reauthentication. Irreversible.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "password": {
                    "type": "string",
                    "description": "Current password, used for recent reauthentication."
                  },
                  "confirm": {
                    "type": "string",
                    "description": "Must equal \"DELETE MY ACCOUNT\"."
                  }
                },
                "required": [
                  "password",
                  "confirm"
                ],
                "additionalProperties": false
              },
              "example": {
                "password": "replace_with_password",
                "confirm": "replace_with_confirm"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "leftBehind": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "leftBehind": [
                          "<leftBehind>"
                        ]
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "delete-account",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/delete-all-data": {
      "post": {
        "operationId": "deleteAllData",
        "summary": "Delete all integrations and data",
        "description": "Remove every integration and all monitoring data (services, history, incidents, alerts, credentials). Notification channels are kept. Pass confirm:\"DELETE\". Irreversible.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "string",
                    "description": "Must equal \"DELETE\" to proceed. Guards against accidental wipes."
                  }
                },
                "required": [
                  "confirm"
                ],
                "additionalProperties": false
              },
              "example": {
                "confirm": "replace_with_confirm"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "deletedIntegrations": {
                          "type": "integer"
                        },
                        "deletedServices": {
                          "type": "integer"
                        },
                        "leftBehind": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "deletedIntegrations": 1,
                        "deletedServices": 1,
                        "leftBehind": [
                          "<leftBehind>"
                        ]
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "delete-all-data",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/delete-notification-channel": {
      "post": {
        "operationId": "deleteNotificationChannel",
        "summary": "Delete notification channel",
        "description": "Delete one of the user's notification channels by id.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Channel id to delete."
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              },
              "example": {
                "id": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "delete-notification-channel",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/delete-organization": {
      "post": {
        "operationId": "deleteOrganization",
        "summary": "Delete an organization",
        "description": "Permanently delete an organization and all of its data (integrations, services, history, members). Owner only.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirmName": {
                    "type": "string",
                    "description": "The organization's exact name, to confirm deletion."
                  },
                  "orgId": {
                    "type": "string",
                    "description": "Organization to delete. Defaults to your active organization."
                  }
                },
                "required": [
                  "confirmName"
                ],
                "additionalProperties": false
              },
              "example": {
                "confirmName": "replace_with_confirm_name",
                "orgId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "delete-organization",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/end-live-activity": {
      "post": {
        "operationId": "endLiveActivity",
        "summary": "End a Live Activity",
        "description": "Tell Beaam an iOS Live Activity has ended on the device, so it stops sending it updates. Used by the Beaam iPhone app.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "activityId": {
                    "type": "string",
                    "description": "ActivityKit's identifier."
                  }
                },
                "required": [
                  "activityId"
                ],
                "additionalProperties": false
              },
              "example": {
                "activityId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "ended": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "ended": false,
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "end-live-activity",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-activation-progress": {
      "post": {
        "operationId": "getActivationProgress",
        "summary": "Get activation progress",
        "description": "Show whether this account has connected monitoring, received its first real signal, and verified its default alert path.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "connected": {
                          "type": "boolean"
                        },
                        "connectedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "firstSignalReceived": {
                          "type": "boolean"
                        },
                        "firstSignalAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "alertPathVerified": {
                          "type": "boolean"
                        },
                        "alertPathVerifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "activated": {
                          "type": "boolean"
                        },
                        "welcomed": {
                          "type": "boolean",
                          "description": "Whether this account has already been shown its welcome."
                        },
                        "welcomedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "connected",
                        "connectedAt",
                        "firstSignalReceived",
                        "firstSignalAt",
                        "alertPathVerified",
                        "alertPathVerifiedAt",
                        "activated",
                        "welcomed",
                        "welcomedAt"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "connected": false,
                        "connectedAt": "2026-01-01T00:00:00.000Z",
                        "firstSignalReceived": false,
                        "firstSignalAt": "2026-01-01T00:00:00.000Z",
                        "alertPathVerified": false,
                        "alertPathVerifiedAt": "2026-01-01T00:00:00.000Z",
                        "activated": false,
                        "welcomed": false,
                        "welcomedAt": "2026-01-01T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-activation-progress",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-alert-route": {
      "post": {
        "operationId": "getAlertRoute",
        "summary": "Preview a service's alert route",
        "description": "Show exactly which notification channels an alert on a service would reach: for a degraded incident, and for a broken one (which adds the organization's defaults). Lists any SMS channel the plan won't text.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service whose alert route to preview."
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "mode": {
                          "type": "string",
                          "enum": [
                            "global",
                            "custom"
                          ]
                        },
                        "degraded": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "broken": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "smsDroppedByPlan": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "mode": "global",
                        "degraded": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "type": "<type>",
                            "label": "<label>"
                          }
                        ],
                        "broken": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "type": "<type>",
                            "label": "<label>"
                          }
                        ],
                        "smsDroppedByPlan": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "type": "<type>",
                            "label": "<label>"
                          }
                        ],
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-alert-route",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-billing": {
      "post": {
        "operationId": "getBilling",
        "summary": "Get billing & plan",
        "description": "Return the active organization's effective plan and usage, plus the caller's own account plan and available billing actions.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tier": {
                          "type": "string",
                          "enum": [
                            "free",
                            "solo"
                          ]
                        },
                        "planName": {
                          "type": "string"
                        },
                        "priceMonthly": {
                          "type": "number"
                        },
                        "usage": {
                          "type": "object"
                        },
                        "limits": {
                          "type": "object"
                        },
                        "sms": {
                          "type": "boolean"
                        },
                        "accountTier": {
                          "type": "string",
                          "enum": [
                            "free",
                            "solo"
                          ]
                        },
                        "planProvidedByOrg": {
                          "type": "boolean"
                        },
                        "subscriptionId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "subscription": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "subscriptionError": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "canUpgrade": {
                          "type": "boolean"
                        },
                        "canManage": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "tier",
                        "planName",
                        "priceMonthly",
                        "usage",
                        "limits",
                        "sms",
                        "accountTier",
                        "planProvidedByOrg",
                        "subscriptionId",
                        "subscription",
                        "subscriptionError",
                        "canUpgrade",
                        "canManage"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "tier": "free",
                        "planName": "<planName>",
                        "priceMonthly": 1,
                        "usage": {},
                        "limits": {},
                        "sms": false,
                        "accountTier": "free",
                        "planProvidedByOrg": false,
                        "subscriptionId": "00000000-0000-4000-8000-000000000000",
                        "subscription": {},
                        "subscriptionError": "<subscriptionError>",
                        "canUpgrade": false,
                        "canManage": false
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-billing",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-live-activity-support": {
      "post": {
        "operationId": "getLiveActivitySupport",
        "summary": "Check Live Activity support",
        "description": "Whether this Beaam server can update iOS Live Activities, so the iPhone app knows whether to start one. Used by the Beaam iPhone app.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "supported": {
                          "type": "boolean"
                        },
                        "reason": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "supported",
                        "reason"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "supported": false,
                        "reason": "<reason>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-live-activity-support",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-webhook-signing-secret": {
      "post": {
        "operationId": "getWebhookSigningSecret",
        "summary": "Get webhook signing secret",
        "description": "Return the Standard Webhooks signing secret for one of your webhook notification channels, so your endpoint can verify that a request really came from Beaam.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channelId": {
                    "type": "string",
                    "description": "Id of the webhook notification channel."
                  }
                },
                "required": [
                  "channelId"
                ],
                "additionalProperties": false
              },
              "example": {
                "channelId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "channelId": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "destination": {
                          "type": "string"
                        },
                        "signingSecret": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "channelId": "00000000-0000-4000-8000-000000000000",
                        "label": "<label>",
                        "destination": "<destination>",
                        "signingSecret": "<secret>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-webhook-signing-secret",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/invite-member": {
      "post": {
        "operationId": "inviteMember",
        "summary": "Invite a member",
        "description": "Invite someone to your active organization by email and get a one-time link to share. Owners and admins only.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Email address of the person to invite."
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "member"
                    ],
                    "description": "Role to grant. Defaults to member."
                  }
                },
                "required": [
                  "email"
                ],
                "additionalProperties": false
              },
              "example": {
                "email": "user@example.com",
                "role": "admin"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        },
                        "acceptUrl": {
                          "type": "string"
                        },
                        "expiresAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "email": "user@example.com",
                        "role": "<role>",
                        "acceptUrl": "https://example.com",
                        "expiresAt": "2026-01-01T00:00:00.000Z"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "invite-member",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/join-waitlist": {
      "post": {
        "operationId": "joinWaitlist",
        "summary": "Join the waitlist",
        "description": "Add an email address to the Beaam waitlist.",
        "tags": [
          "account"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Email to add to the waitlist."
                  },
                  "source": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Where they signed up."
                  }
                },
                "required": [
                  "email"
                ],
                "additionalProperties": false
              },
              "example": {
                "email": "user@example.com",
                "source": "replace_with_source"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "ok"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "ok": false
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "join-waitlist",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/list-api-keys": {
      "post": {
        "operationId": "listApiKeys",
        "summary": "List API keys",
        "description": "Return the caller's API keys — name, prefix, created and last-used times, and whether revoked. Never returns the secret.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "keys": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "prefix": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "last_used_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "expires_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "revoked_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "keys"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "keys": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "name": "<name>",
                            "prefix": "<prefix>",
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "last_used_at": "2026-01-01T00:00:00.000Z",
                            "expires_at": "2026-01-01T00:00:00.000Z",
                            "revoked_at": "2026-01-01T00:00:00.000Z"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-api-keys",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/list-devices": {
      "post": {
        "operationId": "listDevices",
        "summary": "List mobile devices",
        "description": "Return the user's mobile devices registered for push alerts — platform, device name, and when each was last seen. Use unregister-device to remove one.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "devices": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "platform": {
                                "type": "string",
                                "enum": [
                                  "ios",
                                  "android"
                                ]
                              },
                              "device_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "last_seen_at": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "devices"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "devices": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "platform": "ios",
                            "device_name": "<device_name>",
                            "last_seen_at": "2026-01-01T00:00:00.000Z",
                            "created_at": "2026-01-01T00:00:00.000Z"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-devices",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-maintenance-windows": {
      "post": {
        "operationId": "listMaintenanceWindows",
        "summary": "List maintenance windows",
        "description": "Show the planned periods when alerts are withheld, and which of them is silencing you right now.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "includePast": {
                    "type": "boolean",
                    "description": "Include windows that have already closed. Defaults to false."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "includePast": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "windows": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "windows"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "windows": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-maintenance-windows",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-members": {
      "post": {
        "operationId": "listMembers",
        "summary": "List organization members",
        "description": "List the members of your active organization (with roles), plus pending invitations if you can manage members.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "orgId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "myRole": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "enum": [
                            "owner",
                            "admin",
                            "member",
                            null
                          ]
                        },
                        "members": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "userId": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string"
                              },
                              "role": {
                                "type": "string"
                              },
                              "joinedAt": {
                                "type": "string"
                              },
                              "isSelf": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "pendingInvites": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string"
                              },
                              "role": {
                                "type": "string"
                              },
                              "createdAt": {
                                "type": "string"
                              },
                              "expiresAt": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "orgId",
                        "myRole",
                        "members",
                        "pendingInvites"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "orgId": "00000000-0000-4000-8000-000000000000",
                        "myRole": "owner",
                        "members": [
                          {
                            "userId": "00000000-0000-4000-8000-000000000000",
                            "email": "user@example.com",
                            "role": "<role>",
                            "joinedAt": "2026-01-01T00:00:00.000Z",
                            "isSelf": false
                          }
                        ],
                        "pendingInvites": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "email": "user@example.com",
                            "role": "<role>",
                            "createdAt": "2026-01-01T00:00:00.000Z",
                            "expiresAt": "2026-01-01T00:00:00.000Z"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-members",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/list-notification-channels": {
      "post": {
        "operationId": "listNotificationChannels",
        "summary": "List notification channels",
        "description": "Return the user's notification channels (email/SMS/push/Slack/webhook): destination, enabled state, why Beaam disabled it, whether it's a default, and its latest test result. Pass serviceId to also get that service's routing.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "If set, also return this service's routing (global default vs custom channel set)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "channels": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "email",
                                  "sms",
                                  "push",
                                  "slack",
                                  "webhook"
                                ]
                              },
                              "label": {
                                "type": "string"
                              },
                              "destination": {
                                "type": "string"
                              },
                              "enabled": {
                                "type": "boolean"
                              },
                              "is_default": {
                                "type": "boolean"
                              },
                              "consent_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "When SMS consent was affirmed for this destination. Null for non-SMS channels or where no consent is on record."
                              },
                              "disabled_reason": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Why Beaam disabled this channel (e.g. the recipient replied STOP). Null if the user disabled it or it's enabled."
                              },
                              "lastTest": {
                                "type": "object",
                                "description": "The channel's latest test alert. status 'delivered' is proof it reaches you; 'accepted' is still waiting on the provider's receipt; anything else failed, with reason.",
                                "properties": {
                                  "status": {
                                    "type": "string"
                                  },
                                  "sentAt": {
                                    "type": "string"
                                  },
                                  "deliveredAt": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "reason": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                }
                              }
                            }
                          }
                        },
                        "serviceRouting": {
                          "type": "object",
                          "properties": {
                            "mode": {
                              "type": "string",
                              "enum": [
                                "global",
                                "custom"
                              ]
                            },
                            "channelIds": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "sms": {
                          "type": "object",
                          "description": "SMS coverage and this month's allowance: whether the org's plan texts, the caller's spend against the monthly budget and the test allowance (micro-dollars), and the countries SMS reaches.",
                          "properties": {
                            "planAllows": {
                              "type": "boolean"
                            },
                            "spentMicros": {
                              "type": "integer"
                            },
                            "budgetMicros": {
                              "type": "integer"
                            },
                            "testBudgetMicros": {
                              "type": "integer"
                            },
                            "countries": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "heartbeat": {
                          "type": "object",
                          "description": "When the caller's daily heartbeat was last sent, and the earliest it is next due.",
                          "properties": {
                            "lastSentAt": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "nextAfter": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          }
                        }
                      },
                      "required": [
                        "channels"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "channels": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "type": "email",
                            "label": "<label>",
                            "destination": "<destination>",
                            "enabled": false,
                            "is_default": false,
                            "consent_at": "2026-01-01T00:00:00.000Z",
                            "disabled_reason": "<disabled_reason>",
                            "lastTest": {
                              "status": "<status>",
                              "sentAt": "2026-01-01T00:00:00.000Z",
                              "deliveredAt": "2026-01-01T00:00:00.000Z",
                              "reason": "<reason>"
                            }
                          }
                        ],
                        "serviceRouting": {
                          "mode": "global",
                          "channelIds": [
                            "00000000-0000-4000-8000-000000000000"
                          ]
                        },
                        "sms": {
                          "planAllows": false,
                          "spentMicros": 1,
                          "budgetMicros": 1,
                          "testBudgetMicros": 1,
                          "countries": [
                            "<countrie>"
                          ]
                        },
                        "heartbeat": {
                          "lastSentAt": "2026-01-01T00:00:00.000Z",
                          "nextAfter": "<nextAfter>"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-notification-channels",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-organizations": {
      "post": {
        "operationId": "listOrganizations",
        "summary": "List organizations",
        "description": "List the organizations you belong to, your role in each, and which one is currently active.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "organizations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "tier": {
                                "type": "string"
                              },
                              "role": {
                                "type": "string",
                                "enum": [
                                  "owner",
                                  "admin",
                                  "member"
                                ]
                              },
                              "isActive": {
                                "type": "boolean"
                              },
                              "nameSet": {
                                "type": "boolean",
                                "description": "False while the workspace still carries its auto-derived name."
                              },
                              "aiExplanations": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "activeOrgId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "organizations",
                        "activeOrgId"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "organizations": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "name": "<name>",
                            "slug": "<slug>",
                            "tier": "<tier>",
                            "role": "owner",
                            "isActive": false,
                            "nameSet": false,
                            "aiExplanations": false
                          }
                        ],
                        "activeOrgId": "00000000-0000-4000-8000-000000000000"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-organizations",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/list-payments": {
      "post": {
        "operationId": "listPayments",
        "summary": "List payments",
        "description": "Return past payments for the signed-in account, newest first, with amount, status and a receipt link where one exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "payments": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "createdAt": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer"
                              },
                              "currency": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "invoiceUrl": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "payments",
                        "error"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "payments": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "createdAt": "2026-01-01T00:00:00.000Z",
                            "amountCents": 1,
                            "currency": "<currency>",
                            "status": "<status>",
                            "invoiceUrl": "https://example.com"
                          }
                        ],
                        "error": "<error>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-payments",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/preview-invitation": {
      "post": {
        "operationId": "previewInvitation",
        "summary": "Preview an invitation",
        "description": "Look up an organization invitation by token to see the organization, invited email, and role.",
        "tags": [
          "account"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The invitation token from the accept link."
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": false
              },
              "example": {
                "token": "replace_with_token"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "found": {
                          "type": "boolean"
                        },
                        "orgName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        },
                        "expiresAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "found"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "found": false,
                        "orgName": "<orgName>",
                        "email": "user@example.com",
                        "role": "<role>",
                        "expiresAt": "2026-01-01T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "preview-invitation",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/record-product-event": {
      "post": {
        "operationId": "recordProductEvent",
        "summary": "Record a product journey event",
        "description": "Record a non-sensitive setup, integration-selection, or upgrade-intent event for the signed-in account.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "setup_started",
                      "integration_selected",
                      "upgrade_started"
                    ],
                    "description": "A user-intent funnel event. Outcome milestones are recorded by Beaam itself."
                  },
                  "properties": {
                    "type": "object",
                    "description": "Optional non-sensitive context such as provider or entry_point.",
                    "additionalProperties": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean"
                        }
                      ]
                    }
                  }
                },
                "required": [
                  "event"
                ],
                "additionalProperties": false
              },
              "example": {
                "event": "setup_started",
                "properties": {
                  "key": "replace_with_value"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "recorded"
                          ]
                        }
                      },
                      "required": [
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "recorded"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "record-product-event",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/register-device": {
      "post": {
        "operationId": "registerDevice",
        "summary": "Register mobile device",
        "description": "Enroll a mobile device for push alerts using its Expo push token. Creates the push notification channel on first registration; re-registering the same token just refreshes it. A confirmed replaceExisting request moves the physical device from a previous account.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expoPushToken": {
                    "type": "string",
                    "description": "The device's Expo push token, e.g. ExponentPushToken[xxxx]."
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "ios",
                      "android"
                    ]
                  },
                  "deviceName": {
                    "type": "string",
                    "description": "Human label for the device, e.g. \"Nick's iPhone\"."
                  },
                  "replaceExisting": {
                    "type": "boolean",
                    "description": "After explicit confirmation, move this physical device from a previous Beaam account to the current account."
                  }
                },
                "required": [
                  "expoPushToken",
                  "platform"
                ],
                "additionalProperties": false
              },
              "example": {
                "expoPushToken": "replace_with_token",
                "platform": "ios",
                "deviceName": "replace_with_device_name",
                "replaceExisting": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "deviceId": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "device_registered_elsewhere"
                          ]
                        },
                        "transferred": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "deviceId": "00000000-0000-4000-8000-000000000000",
                        "code": "device_registered_elsewhere",
                        "transferred": false
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "register-device",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/register-live-activity": {
      "post": {
        "operationId": "registerLiveActivity",
        "summary": "Register a Live Activity",
        "description": "Register an iOS Live Activity's push token for an open incident, so Beaam can update it and end it when the incident resolves. Used by the Beaam iPhone app.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The open incident the activity shows."
                  },
                  "activityId": {
                    "type": "string",
                    "description": "ActivityKit's identifier for the activity."
                  },
                  "pushToken": {
                    "type": "string",
                    "description": "The activity's APNs push token, hex."
                  },
                  "apnsEnvironment": {
                    "type": "string",
                    "enum": [
                      "production",
                      "sandbox"
                    ],
                    "description": "sandbox for development builds; production otherwise."
                  }
                },
                "required": [
                  "incidentId",
                  "activityId",
                  "pushToken"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "activityId": "00000000-0000-4000-8000-000000000000",
                "pushToken": "replace_with_token",
                "apnsEnvironment": "production"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "liveActivityId": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "liveActivityId": "00000000-0000-4000-8000-000000000000",
                        "code": "<code>",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "register-live-activity",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/remove-member": {
      "post": {
        "operationId": "removeMember",
        "summary": "Remove a member",
        "description": "Remove a member from your active organization, revoking their access. Owners and admins only.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "The user id of the member to remove."
                  }
                },
                "required": [
                  "userId"
                ],
                "additionalProperties": false
              },
              "example": {
                "userId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "remove-member",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/rename-organization": {
      "post": {
        "operationId": "renameOrganization",
        "summary": "Rename an organization",
        "description": "Rename an organization (defaults to your active one). Owners and admins only.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The new organization name."
                  },
                  "orgId": {
                    "type": "string",
                    "description": "Organization to rename. Defaults to your active organization."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "replace_with_name",
                "orgId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "id": "00000000-0000-4000-8000-000000000000",
                        "name": "<name>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "rename-organization",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/resume-subscription": {
      "post": {
        "operationId": "resumeSubscription",
        "summary": "Resume subscription",
        "description": "Undo a scheduled cancellation so the caller's Solo subscription renews as normal instead of ending at the current period.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "resume-subscription",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/revoke-api-key": {
      "post": {
        "operationId": "revokeApiKey",
        "summary": "Revoke an API key",
        "description": "Revoke a personal API key by id; it stops working immediately.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The API key id to revoke."
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              },
              "example": {
                "id": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "revoke-api-key",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/revoke-assistant-connection": {
      "post": {
        "operationId": "revokeAssistantConnection",
        "summary": "Disconnect an AI assistant",
        "description": "End one AI client's access to this Beaam account. Its live tokens are revoked and any pending authorization is discarded, so it stops working immediately. Other connected clients are unaffected; reconnecting means authorizing again.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "description": "Client id of the connection to revoke, from list-assistant-connections."
                  }
                },
                "required": [
                  "clientId"
                ],
                "additionalProperties": false
              },
              "example": {
                "clientId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "revoked": {
                          "type": "number"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "revoked",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "revoked": 1,
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "revoke-assistant-connection",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/revoke-invitation": {
      "post": {
        "operationId": "revokeInvitation",
        "summary": "Revoke an invitation",
        "description": "Revoke a pending invitation to your active organization, invalidating its link. Owners and admins only.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "inviteId": {
                    "type": "string",
                    "description": "The id of the pending invitation to revoke."
                  }
                },
                "required": [
                  "inviteId"
                ],
                "additionalProperties": false
              },
              "example": {
                "inviteId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "revoke-invitation",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/rotate-webhook-signing-secret": {
      "post": {
        "operationId": "rotateWebhookSigningSecret",
        "summary": "Rotate webhook signing secret",
        "description": "Issue a new Standard Webhooks signing secret for one of your webhook notification channels. The change takes effect immediately and the previous secret stops working, so update your endpoint at the same time.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channelId": {
                    "type": "string",
                    "description": "Id of the webhook notification channel."
                  }
                },
                "required": [
                  "channelId"
                ],
                "additionalProperties": false
              },
              "example": {
                "channelId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "channelId": {
                          "type": "string"
                        },
                        "signingSecret": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "channelId": "00000000-0000-4000-8000-000000000000",
                        "signingSecret": "<secret>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "rotate-webhook-signing-secret",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/save-notification-channel": {
      "post": {
        "operationId": "saveNotificationChannel",
        "summary": "Save notification channel",
        "description": "Create or update a notification channel. type is email, sms, push, slack, or webhook; destination is an email address, E.164 phone, or https:// webhook URL. SMS channels require the Solo plan. Push channels can only be updated here — they're created by registering a device.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.\n\n**Has an outside-world side effect** — it sends something (an email, an SMS).",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Existing channel id to update; omit to create."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "email",
                      "sms",
                      "push",
                      "slack",
                      "webhook"
                    ]
                  },
                  "label": {
                    "type": "string",
                    "description": "Human label, e.g. 'On-call SMS'."
                  },
                  "destination": {
                    "type": "string",
                    "description": "Email address, E.164 phone number, or https:// webhook URL (slack = a Slack incoming webhook; webhook = any endpoint that accepts a JSON POST). Ignored for push (delivery goes to registered devices)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether this channel can fire."
                  },
                  "isDefault": {
                    "type": "boolean",
                    "description": "Include in the global default routing set used by services with no override."
                  },
                  "smsConsent": {
                    "type": "boolean",
                    "description": "Required for SMS channels: confirms the person holding this number agreed to receive Beaam Alerts texts, having been shown the program name, that frequency varies, that message and data rates may apply, and how to stop. Needed when creating an SMS channel, re-enabling a disabled one, or changing its number. Must reflect a real affirmative act by that person — not a default."
                  }
                },
                "required": [
                  "type",
                  "label",
                  "destination"
                ],
                "additionalProperties": false
              },
              "example": {
                "id": "00000000-0000-4000-8000-000000000000",
                "type": "email",
                "label": "replace_with_label",
                "destination": "replace_with_destination",
                "enabled": false,
                "isDefault": false,
                "smsConsent": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "warning": {
                          "type": "string",
                          "description": "Saved, but something did not happen that the user should know about (e.g. the SMS opt-in confirmation text failed)."
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "id": "00000000-0000-4000-8000-000000000000",
                        "warning": "<warning>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "save-notification-channel",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": true,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/schedule-maintenance-window": {
      "post": {
        "operationId": "scheduleMaintenanceWindow",
        "summary": "Schedule a maintenance window",
        "description": "Plan a period when Beaam should not page you — a deploy or migration. Incidents are still detected and recorded; only the alert is withheld, with your reason attached. Never silences the checks that tell you Beaam itself stopped watching.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "startsAt": {
                    "type": "string",
                    "description": "When the window opens: ISO 8601 with an offset or Z, e.g. 2026-10-07T10:00:00+02:00."
                  },
                  "endsAt": {
                    "type": "string",
                    "description": "When it closes, ISO 8601 with an offset or Z. Required — silence is always bounded."
                  },
                  "reason": {
                    "type": "string",
                    "description": "Why, in a few words. Shown on the withheld alert."
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "org",
                      "stack",
                      "service"
                    ],
                    "description": "Everything, one stack, or one service. Defaults to service when a serviceId is given."
                  },
                  "stackId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Required for scope 'stack'."
                  },
                  "serviceId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Required for scope 'service'."
                  }
                },
                "required": [
                  "startsAt",
                  "endsAt",
                  "reason"
                ],
                "additionalProperties": false
              },
              "example": {
                "startsAt": "2026-01-01T00:00:00.000Z",
                "endsAt": "2026-01-01T00:00:00.000Z",
                "reason": "replace_with_reason",
                "scope": "org",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "windowId": {
                          "type": "string"
                        },
                        "startsAt": {
                          "type": "string"
                        },
                        "endsAt": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "windowId": "00000000-0000-4000-8000-000000000000",
                        "startsAt": "2026-01-01T00:00:00.000Z",
                        "endsAt": "2026-01-01T00:00:00.000Z",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "schedule-maintenance-window",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/send-test-alert": {
      "post": {
        "operationId": "sendTestAlert",
        "summary": "Send a test alert",
        "description": "Send a harmless test alert through your real notification channels (email, SMS, push, Slack, or webhook) and report whether each delivery worked. Omit channelId to test all enabled default channels.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Has an outside-world side effect** — it sends something (an email, an SMS).",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channelId": {
                    "type": "string",
                    "description": "Test a single channel by id. Omit to test every enabled default channel."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "channelId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "channelId": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "email",
                                  "sms",
                                  "push",
                                  "slack",
                                  "webhook"
                                ]
                              },
                              "label": {
                                "type": "string"
                              },
                              "sent": {
                                "type": "boolean"
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "delivered",
                                  "accepted",
                                  "failed"
                                ]
                              },
                              "testId": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "status",
                        "results"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "results": [
                          {
                            "channelId": "00000000-0000-4000-8000-000000000000",
                            "type": "email",
                            "label": "<label>",
                            "sent": false,
                            "state": "delivered",
                            "testId": "00000000-0000-4000-8000-000000000000",
                            "reason": "<reason>"
                          }
                        ]
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "send-test-alert",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": true,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-ai-explanations": {
      "post": {
        "operationId": "setAiExplanations",
        "summary": "Set AI incident explanations",
        "description": "Turn AI incident explanations on or off for your organization. When on, Beaam may send a short incident evidence summary to an LLM to write a one-sentence explanation; when off, no incident data is ever sent to an LLM.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "Turn AI incident explanations on or off for the organization."
                  },
                  "orgId": {
                    "type": "string",
                    "description": "Organization to change. Defaults to your active organization."
                  }
                },
                "required": [
                  "enabled"
                ],
                "additionalProperties": false
              },
              "example": {
                "enabled": false,
                "orgId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "enabled": false
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-ai-explanations",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/set-service-notifications": {
      "post": {
        "operationId": "setServiceNotifications",
        "summary": "Set service notifications",
        "description": "Choose how a service's alerts route: 'global' uses the default channels; 'custom' uses the given channelIds. Pass the service id and mode.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "global",
                      "custom"
                    ],
                    "description": "global = use the default channel set; custom = use channelIds."
                  },
                  "channelIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Channel ids to route to when mode is custom."
                  }
                },
                "required": [
                  "serviceId",
                  "mode"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "mode": "global",
                "channelIds": [
                  "00000000-0000-4000-8000-000000000000"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "mode": {
                          "type": "string",
                          "enum": [
                            "global",
                            "custom"
                          ]
                        },
                        "channelCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "mode": "global",
                        "channelCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-service-notifications",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/switch-organization": {
      "post": {
        "operationId": "switchOrganization",
        "summary": "Switch active organization",
        "description": "Make one of your organizations the active one for the current session. You must be a member of it.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orgId": {
                    "type": "string",
                    "description": "The organization to make active."
                  }
                },
                "required": [
                  "orgId"
                ],
                "additionalProperties": false
              },
              "example": {
                "orgId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "switch-organization",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/unregister-device": {
      "post": {
        "operationId": "unregisterDevice",
        "summary": "Unregister mobile device",
        "description": "Remove a mobile device from push alerting, by device id or by its Expo push token. Removing the last device also removes the push notification channel; registering again restores it.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "deviceId": {
                    "type": "string",
                    "description": "Device id from list-devices."
                  },
                  "expoPushToken": {
                    "type": "string",
                    "description": "Alternatively, the device's own Expo push token."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "deviceId": "00000000-0000-4000-8000-000000000000",
                "expoPushToken": "replace_with_token"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "unregister-device",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/acknowledge-incident": {
      "post": {
        "operationId": "acknowledgeIncident",
        "summary": "Acknowledge an incident",
        "description": "Mark an incident as being handled (\"I'm on it\"), or clear that. Quiets Beaam about it while you work on it.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The incident to acknowledge."
                  },
                  "acknowledged": {
                    "type": "boolean",
                    "description": "True to acknowledge (\"I'm on it\"); false to clear it."
                  }
                },
                "required": [
                  "incidentId"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "acknowledged": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "incidentId": {
                          "type": "string"
                        },
                        "acknowledged": {
                          "type": "boolean"
                        },
                        "acknowledgedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "incidentId",
                        "acknowledged",
                        "acknowledgedAt"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "incidentId": "00000000-0000-4000-8000-000000000000",
                        "acknowledged": false,
                        "acknowledgedAt": "2026-01-01T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "acknowledge-incident",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/add-incident-note": {
      "post": {
        "operationId": "addIncidentNote",
        "summary": "Add a note to an incident",
        "description": "Record what happened on an incident — the cause, what was done, or what is still unknown. Notes are permanent and cannot be edited or deleted, so they keep what was believed at the time.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The incident to annotate."
                  },
                  "body": {
                    "type": "string",
                    "description": "What happened, what was done, or what is still unknown.",
                    "maxLength": 4000
                  }
                },
                "required": [
                  "incidentId",
                  "body"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "body": "replace_with_body"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "noteId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "noteId": "00000000-0000-4000-8000-000000000000",
                        "createdAt": "2026-01-01T00:00:00.000Z",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "add-incident-note",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/cancel-incident-reminder": {
      "post": {
        "operationId": "cancelIncidentReminder",
        "summary": "Cancel an incident reminder",
        "description": "Withdraw your pending reminder about an incident, so no reminder push is sent. Says whether there was one to cancel.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The incident whose pending reminder to cancel."
                  }
                },
                "required": [
                  "incidentId"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "cancelled": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "status",
                        "cancelled"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "cancelled": false
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "cancel-incident-reminder",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-history-overview": {
      "post": {
        "operationId": "getHistoryOverview",
        "summary": "Get History overview",
        "description": "Return the active organization's bounded History page payload.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "description": "Everything the History screen shows, in one read.",
                      "properties": {
                        "incidents": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "suppressions": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "alerts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "incident_id": {
                                "type": "string"
                              },
                              "channel": {
                                "type": "string"
                              },
                              "content": {
                                "type": "string"
                              },
                              "sent_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "user_acknowledged_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "was_real_incident": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "delivery_status": {
                                "type": "string",
                                "description": "pending, accepted (a provider took it), delayed, delivered (provider-confirmed), bounced, complained, suppressed, failed, exhausted or skipped."
                              },
                              "delivered_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "last_error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        },
                        "serviceNames": {
                          "type": "object",
                          "description": "Service display names keyed by service id.",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "incidentServiceIds": {
                          "type": "object",
                          "description": "The service each incident belongs to, keyed by incident id.",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "alertsSent": {
                              "type": "integer"
                            },
                            "confirmedReal": {
                              "type": "integer"
                            },
                            "falseAlarms": {
                              "type": "integer"
                            },
                            "unreviewed": {
                              "type": "integer"
                            },
                            "incidents": {
                              "type": "integer"
                            },
                            "openIncidents": {
                              "type": "integer"
                            },
                            "suppressions": {
                              "type": "integer"
                            },
                            "falseAlarmRate": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          },
                          "required": [
                            "alertsSent",
                            "confirmedReal",
                            "falseAlarms",
                            "unreviewed",
                            "incidents",
                            "openIncidents",
                            "suppressions",
                            "falseAlarmRate"
                          ]
                        }
                      },
                      "required": [
                        "incidents",
                        "suppressions",
                        "alerts",
                        "serviceNames",
                        "incidentServiceIds",
                        "stats"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "incidents": [
                          {}
                        ],
                        "suppressions": [
                          {}
                        ],
                        "alerts": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "incident_id": "00000000-0000-4000-8000-000000000000",
                            "channel": "<channel>",
                            "content": "<content>",
                            "sent_at": "2026-01-01T00:00:00.000Z",
                            "user_acknowledged_at": "2026-01-01T00:00:00.000Z",
                            "was_real_incident": false,
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "delivery_status": "<delivery_status>",
                            "delivered_at": "2026-01-01T00:00:00.000Z",
                            "last_error": "<last_error>"
                          }
                        ],
                        "serviceNames": {
                          "key": "<value>"
                        },
                        "incidentServiceIds": {
                          "key": "<value>"
                        },
                        "stats": {
                          "alertsSent": 1,
                          "confirmedReal": 1,
                          "falseAlarms": 1,
                          "unreviewed": 1,
                          "incidents": 1,
                          "openIncidents": 1,
                          "suppressions": 1,
                          "falseAlarmRate": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-history-overview",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-incident": {
      "post": {
        "operationId": "getIncident",
        "summary": "Get an incident",
        "description": "Fetch a single incident by id, with its current state and acknowledgement/snooze status.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The incident to fetch."
                  }
                },
                "required": [
                  "incidentId"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "incident": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "reminder": {
                          "type": [
                            "object",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "incident",
                        "reminder"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "incident": {},
                        "reminder": {}
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-incident",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-service-history": {
      "post": {
        "operationId": "getServiceHistory",
        "summary": "Get service history",
        "description": "Return a service's complete retained-window uptime and latency summary, bounded chart series, latest check, and collapsed state runs.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string"
                  },
                  "since": {
                    "type": "string"
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "since": "2026-01-01T00:00:00.000Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "summary": {
                          "type": "object",
                          "description": "Totals over the window: checks, quiet checks, uptime and p95 latency (null when nothing was measured).",
                          "properties": {
                            "totalChecks": {
                              "type": "integer"
                            },
                            "quietChecks": {
                              "type": "integer"
                            },
                            "uptimePercent": {
                              "type": [
                                "number",
                                "null"
                              ]
                            },
                            "p95LatencyMs": {
                              "type": [
                                "number",
                                "null"
                              ]
                            },
                            "hasHttp": {
                              "type": "boolean"
                            },
                            "hasLatency": {
                              "type": "boolean"
                            },
                            "hasError": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "totalChecks",
                            "quietChecks",
                            "uptimePercent",
                            "p95LatencyMs",
                            "hasHttp",
                            "hasLatency",
                            "hasError"
                          ]
                        },
                        "latest": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "The most recent check, or null when the service has none.",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "checked_at": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "latency_ms": {
                              "type": [
                                "number",
                                "null"
                              ]
                            },
                            "http_status": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "tool_call_success": {
                              "type": [
                                "boolean",
                                "null"
                              ]
                            },
                            "tool_call_error": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "metrics": {
                              "type": [
                                "object",
                                "null"
                              ],
                              "additionalProperties": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "dailyUptime": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "day": {
                                "type": "string"
                              },
                              "uptime": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "day",
                              "uptime"
                            ]
                          }
                        },
                        "latencySeries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "checkedAt": {
                                "type": "string"
                              },
                              "value": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "checkedAt",
                              "value"
                            ]
                          }
                        },
                        "metricSeries": {
                          "type": "object",
                          "description": "One series per collected metric, keyed by metric name.",
                          "additionalProperties": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "checkedAt": {
                                  "type": "string"
                                },
                                "value": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "checkedAt",
                                "value"
                              ]
                            }
                          }
                        },
                        "runs": {
                          "type": "array",
                          "description": "Consecutive checks with the same outcome, newest first.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "http_status": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "latency_ms": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "latencyMin": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "latencyMax": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "tool_call_error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "latestAt": {
                                "type": "string"
                              },
                              "oldestAt": {
                                "type": "string"
                              },
                              "count": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "summary",
                        "latest",
                        "dailyUptime",
                        "latencySeries",
                        "metricSeries",
                        "runs"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "summary": {
                          "totalChecks": 1,
                          "quietChecks": 1,
                          "uptimePercent": 1,
                          "p95LatencyMs": 1,
                          "hasHttp": false,
                          "hasLatency": false,
                          "hasError": false
                        },
                        "latest": {
                          "id": "00000000-0000-4000-8000-000000000000",
                          "checked_at": "2026-01-01T00:00:00.000Z",
                          "status": "<status>",
                          "latency_ms": 1,
                          "http_status": 1,
                          "tool_call_success": false,
                          "tool_call_error": "<tool_call_error>",
                          "metrics": {
                            "key": 1
                          }
                        },
                        "dailyUptime": [
                          {
                            "day": "<day>",
                            "uptime": 1
                          }
                        ],
                        "latencySeries": [
                          {
                            "checkedAt": "2026-01-01T00:00:00.000Z",
                            "value": 1
                          }
                        ],
                        "metricSeries": {
                          "key": [
                            {
                              "checkedAt": "2026-01-01T00:00:00.000Z",
                              "value": 1
                            }
                          ]
                        },
                        "runs": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "status": "<status>",
                            "http_status": 1,
                            "latency_ms": 1,
                            "latencyMin": 1,
                            "latencyMax": 1,
                            "tool_call_error": "<tool_call_error>",
                            "latestAt": "2026-01-01T00:00:00.000Z",
                            "oldestAt": "2026-01-01T00:00:00.000Z",
                            "count": 25
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-service-history",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-service-timeline": {
      "post": {
        "operationId": "getServiceTimeline",
        "summary": "Get a service's timeline",
        "description": "What happened around one service, in order — the deploys and config changes across its stack alongside the incidents it opened and resolved, so a change and the failure that followed it read as one sequence.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service to build a timeline for."
                  },
                  "hours": {
                    "type": "number",
                    "description": "How far back to look (1–168, default 24). Ignored when `from` is given."
                  },
                  "from": {
                    "type": "string",
                    "description": "Start of an absolute window (ISO 8601). With `to`, at most 168 hours long."
                  },
                  "to": {
                    "type": "string",
                    "description": "End of the absolute window (ISO 8601). Defaults to now, and never later than now."
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "hours": 1,
                "from": "2026-01-01T00:00:00.000Z",
                "to": "2026-01-01T00:00:00.000Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "entries": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "hours": {
                          "type": "number"
                        },
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "complete": {
                          "type": "boolean"
                        },
                        "gaps": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "entries",
                        "hours",
                        "from",
                        "to",
                        "complete",
                        "gaps"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "entries": [
                          {}
                        ],
                        "hours": 1,
                        "from": "2026-01-01T00:00:00.000Z",
                        "to": "2026-01-01T00:00:00.000Z",
                        "complete": false,
                        "gaps": [
                          "<gap>"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-service-timeline",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-active-problems": {
      "post": {
        "operationId": "listActiveProblems",
        "summary": "List active problems",
        "description": "Everything open right now, grouped into events (related incidents together) and ordered by what needs you first: unanswered, then most severe, then largest, then most recent.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "problems": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "incidentCount": {
                          "type": "integer"
                        },
                        "truncated": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "problems",
                        "incidentCount",
                        "truncated"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "problems": [
                          {}
                        ],
                        "incidentCount": 25,
                        "truncated": false
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-active-problems",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-alerts": {
      "post": {
        "operationId": "listAlerts",
        "summary": "List alerts",
        "description": "Return the alerts Beaam has sent, newest first, with each alert's review state (real incident, false alarm, or unreviewed).",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "unreviewedOnly": {
                    "type": "boolean",
                    "description": "Only alerts not yet tagged real / false-alarm."
                  },
                  "incidentId": {
                    "type": "string",
                    "description": "Only return alerts sent for this incident."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max rows, newest first (default 50, max 200)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "unreviewedOnly": false,
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "limit": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "alerts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "incident_id": {
                                "type": "string"
                              },
                              "channel": {
                                "type": "string"
                              },
                              "content": {
                                "type": "string"
                              },
                              "sent_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "user_acknowledged_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "was_real_incident": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "delivery_status": {
                                "type": "string",
                                "description": "pending, accepted (a provider took it), delayed, delivered (provider-confirmed), bounced, complained, suppressed, failed, exhausted or skipped."
                              },
                              "delivered_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "last_error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "alerts"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "alerts": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "incident_id": "00000000-0000-4000-8000-000000000000",
                            "channel": "<channel>",
                            "content": "<content>",
                            "sent_at": "2026-01-01T00:00:00.000Z",
                            "user_acknowledged_at": "2026-01-01T00:00:00.000Z",
                            "was_real_incident": false,
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "delivery_status": "<delivery_status>",
                            "delivered_at": "2026-01-01T00:00:00.000Z",
                            "last_error": "<last_error>"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-alerts",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-checks": {
      "post": {
        "operationId": "listChecks",
        "summary": "List checks",
        "description": "Return recent poll results (checks) for the user's services — newest first — optionally filtered to one or more services and a closed time window. Reports when the window predates the 30-day raw-retention limit, so an empty result is never mistaken for a quiet period.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "Limit to one service."
                  },
                  "serviceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Limit to these services."
                  },
                  "since": {
                    "type": "string",
                    "description": "ISO timestamp; only return checks at or after this time."
                  },
                  "until": {
                    "type": "string",
                    "description": "ISO timestamp; only return checks strictly before this time. With `since`, selects a closed window."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max rows, newest first (default 100, max 2000)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "serviceIds": [
                  "00000000-0000-4000-8000-000000000000"
                ],
                "since": "2026-01-01T00:00:00.000Z",
                "until": "2026-01-01T00:00:00.000Z",
                "limit": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "checks": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "retentionCutoff": {
                          "type": "string"
                        },
                        "beyondRetention": {
                          "type": "boolean"
                        },
                        "truncated": {
                          "type": "boolean"
                        },
                        "metricLabels": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "checks",
                        "retentionCutoff",
                        "beyondRetention",
                        "truncated",
                        "metricLabels"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "checks": [
                          {}
                        ],
                        "retentionCutoff": "<retentionCutoff>",
                        "beyondRetention": false,
                        "truncated": false,
                        "metricLabels": {
                          "key": "<value>"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-checks",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-incidents": {
      "post": {
        "operationId": "listIncidents",
        "summary": "List incidents",
        "description": "Return the signed-in user's incidents (the times Beaam decided something was genuinely wrong), newest first.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "openOnly": {
                    "type": "boolean",
                    "description": "Only currently-open incidents."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max rows (default 50)."
                  },
                  "serviceId": {
                    "type": "string",
                    "description": "Only incidents of this service."
                  },
                  "before": {
                    "type": "string",
                    "description": "ISO timestamp cursor: only incidents opened before it. Use the previous page's nextBefore."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "openOnly": false,
                "limit": 25,
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "before": "replace_with_before"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "incidents": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "nextBefore": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Pass as `before` to fetch the next page; null when there are no more incidents."
                        }
                      },
                      "required": [
                        "incidents",
                        "nextBefore"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "incidents": [
                          {}
                        ],
                        "nextBefore": "<nextBefore>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-incidents",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-recent-changes": {
      "post": {
        "operationId": "listRecentChanges",
        "summary": "List recent changes",
        "description": "Return recent control-plane changes across your connected providers — deploys, config edits, scaling and pauses — newest first.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "number",
                    "description": "How many changes to return (1–50, default 10)."
                  },
                  "integrationId": {
                    "type": "string",
                    "description": "Only changes from this connection. Omit for the whole estate."
                  }
                }
              },
              "example": {
                "limit": 25,
                "integrationId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "changes": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "summary": {
                                "type": "string"
                              },
                              "resource": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "occurred_at": {
                                "type": "string"
                              },
                              "integration_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "integration_label": {
                                "type": "string"
                              },
                              "integration_type": {
                                "type": "string"
                              },
                              "stack_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "stack_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "changes"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "changes": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "kind": "<kind>",
                            "summary": "<summary>",
                            "resource": "<resource>",
                            "occurred_at": "2026-01-01T00:00:00.000Z",
                            "integration_id": "00000000-0000-4000-8000-000000000000",
                            "integration_label": "<integration_label>",
                            "integration_type": "<integration_type>",
                            "stack_id": "00000000-0000-4000-8000-000000000000",
                            "stack_name": "<stack_name>"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-recent-changes",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-suppressions": {
      "post": {
        "operationId": "listSuppressions",
        "summary": "List suppressions",
        "description": "Return what Beaam noticed but chose not to alert on (and why), newest first.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "integer",
                    "description": "Max rows (default 50)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "limit": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "suppressions": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "suppressions"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "suppressions": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-suppressions",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/record-deploy": {
      "post": {
        "operationId": "recordDeploy",
        "summary": "Record a deploy",
        "description": "Tell Beaam you deployed, so it can offer that as the explanation when something breaks shortly afterwards. Use it from CI, or anywhere a provider cannot report deploys for you — a VPS, a container host, a manual release.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stack": {
                    "type": "string",
                    "description": "Stack slug or id — the scope this deploy can explain failures within."
                  },
                  "version": {
                    "type": "string",
                    "description": "What was deployed: a commit sha, tag, or release name."
                  },
                  "service": {
                    "type": "string",
                    "description": "Optional. Narrow the deploy to one service, by id or provider external id. Omit for a whole-stack deploy."
                  },
                  "summary": {
                    "type": "string",
                    "description": "Optional. Overrides the generated sentence shown in alerts."
                  },
                  "occurredAt": {
                    "type": "string",
                    "description": "Optional ISO 8601 timestamp. Defaults to now."
                  }
                },
                "required": [
                  "stack",
                  "version"
                ],
                "additionalProperties": false
              },
              "example": {
                "stack": "replace_with_stack",
                "version": "replace_with_version",
                "service": "replace_with_service",
                "summary": "replace_with_summary",
                "occurredAt": "2026-01-01T00:00:00.000Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "recorded": {
                          "type": "boolean"
                        },
                        "duplicate": {
                          "type": "boolean"
                        },
                        "stackId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "summary": {
                          "type": "string"
                        },
                        "occurredAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "recorded",
                        "duplicate",
                        "stackId",
                        "serviceId",
                        "summary",
                        "occurredAt"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "recorded": false,
                        "duplicate": false,
                        "stackId": "00000000-0000-4000-8000-000000000000",
                        "serviceId": "00000000-0000-4000-8000-000000000000",
                        "summary": "<summary>",
                        "occurredAt": "2026-01-01T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "record-deploy",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/review-alert": {
      "post": {
        "operationId": "reviewAlert",
        "summary": "Review an alert",
        "description": "Mark a past alert — or every alert of one incident — as a real incident or a false alarm, so Beaam can track and tune its accuracy.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "alertId": {
                    "type": "string",
                    "description": "The alert to review. Give this or incidentId."
                  },
                  "incidentId": {
                    "type": "string",
                    "description": "Review every alert sent for this incident at once. Give this or alertId."
                  },
                  "wasReal": {
                    "type": "boolean",
                    "description": "True if it was a real incident."
                  }
                },
                "required": [
                  "wasReal"
                ],
                "additionalProperties": false
              },
              "example": {
                "alertId": "00000000-0000-4000-8000-000000000000",
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "wasReal": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean"
                        },
                        "reviewed": {
                          "type": "integer",
                          "description": "How many alert rows the verdict was recorded on."
                        }
                      },
                      "required": [
                        "ok",
                        "reviewed"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "ok": false,
                        "reviewed": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "review-alert",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-incident-reminder": {
      "post": {
        "operationId": "setIncidentReminder",
        "summary": "Remind me if an incident is still open",
        "description": "Get one push on your own phone later, only if the incident hasn't resolved by then. Asking again moves the reminder; it never repeats. 5 minutes to 24 hours ahead.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The open incident to be reminded about."
                  },
                  "minutes": {
                    "type": "integer",
                    "description": "How long from now (5–1440 minutes)."
                  }
                },
                "required": [
                  "incidentId",
                  "minutes"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "minutes": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "reminder": {
                          "type": "object"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "reminder": {},
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-incident-reminder",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/snooze-incident": {
      "post": {
        "operationId": "snoozeIncident",
        "summary": "Snooze an incident",
        "description": "Stay quiet about an incident for a while (\"not now\"). Pass minutes to snooze, or 0 to clear it.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "history"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The incident to snooze."
                  },
                  "minutes": {
                    "type": "integer",
                    "description": "How long to stay quiet, in minutes. 0 (or less) clears the snooze. Capped at one week."
                  }
                },
                "required": [
                  "incidentId",
                  "minutes"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000",
                "minutes": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "incidentId": {
                          "type": "string"
                        },
                        "snoozedUntil": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "incidentId",
                        "snoozedUntil"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "incidentId": "00000000-0000-4000-8000-000000000000",
                        "snoozedUntil": "<snoozedUntil>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "snooze-incident",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/apply-monitoring-plan": {
      "post": {
        "operationId": "applyMonitoringPlan",
        "summary": "Apply an approved monitoring plan",
        "description": "Apply a plan-monitoring result. Answer every returned question using only its stored option values; then Beaam watches selected URLs and guides credentialed connections one at a time. Give the user next.url, poll check-oauth-connect with next.state, then call next-connection. Single-use.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "planId": {
                    "type": "string",
                    "description": "The planId returned by plan-monitoring. Single-use and expires in 30 minutes."
                  },
                  "answers": {
                    "type": "object",
                    "description": "Answers to any questions returned by plan-monitoring. Values must be copied exactly from each question's options.",
                    "properties": {
                      "productionUrls": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Production URL option values the user approved for watching."
                      },
                      "confirmedProviders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Provider option values the user confirmed they actually run on."
                      },
                      "confirmedUnreachableUrls": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Unreachable URL option values the user explicitly approved anyway."
                      },
                      "accountSelections": {
                        "type": "array",
                        "description": "One exact option value for each provider-account:* question.",
                        "items": {
                          "type": "object",
                          "properties": {
                            "questionId": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "questionId",
                            "value"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "stackId": {
                        "type": "string",
                        "description": "Exact option value from the target-stack question."
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "planId"
                ],
                "additionalProperties": false
              },
              "example": {
                "planId": "00000000-0000-4000-8000-000000000000",
                "answers": {
                  "productionUrls": [
                    "https://example.com"
                  ],
                  "confirmedProviders": [
                    "replace_with_confirmed_provider"
                  ],
                  "confirmedUnreachableUrls": [
                    "https://example.com"
                  ],
                  "accountSelections": [
                    {
                      "questionId": "provider-account:cloudflare",
                      "value": "replace_with_value"
                    }
                  ],
                  "stackId": "00000000-0000-4000-8000-000000000000"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "connected": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "detail": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "name",
                              "detail"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "needsBrowser": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "provider": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "stackId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "provider",
                              "label",
                              "url",
                              "stackId"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "needsToken": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "provider": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "capability": {
                                "type": "string"
                              },
                              "stackId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "provider",
                              "label",
                              "capability",
                              "stackId"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "failed": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "name",
                              "reason"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "cannot": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "name",
                              "reason"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "provider": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "url": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "state": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "capability": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "stackId": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "provider",
                            "label",
                            "url",
                            "state",
                            "capability",
                            "stackId"
                          ],
                          "additionalProperties": false
                        },
                        "pollWith": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "targetStack": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "id": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "name": {
                              "type": "string"
                            },
                            "environment": {
                              "type": "string"
                            },
                            "willCreate": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "environment",
                            "willCreate"
                          ],
                          "additionalProperties": false
                        },
                        "summary": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "connected",
                        "needsBrowser",
                        "needsToken",
                        "failed",
                        "cannot",
                        "next",
                        "pollWith",
                        "targetStack",
                        "summary"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "connected": [
                          {
                            "name": "<name>",
                            "detail": "<detail>"
                          }
                        ],
                        "needsBrowser": [
                          {
                            "provider": "cloudflare",
                            "label": "<label>",
                            "url": "https://example.com",
                            "stackId": "00000000-0000-4000-8000-000000000000"
                          }
                        ],
                        "needsToken": [
                          {
                            "provider": "cloudflare",
                            "label": "<label>",
                            "capability": "<capability>",
                            "stackId": "00000000-0000-4000-8000-000000000000"
                          }
                        ],
                        "failed": [
                          {
                            "name": "<name>",
                            "reason": "<reason>"
                          }
                        ],
                        "cannot": [
                          {
                            "name": "<name>",
                            "reason": "<reason>"
                          }
                        ],
                        "next": {
                          "provider": "cloudflare",
                          "label": "<label>",
                          "url": "https://example.com",
                          "state": "<state>",
                          "capability": "<capability>",
                          "stackId": "00000000-0000-4000-8000-000000000000"
                        },
                        "pollWith": "<pollWith>",
                        "targetStack": {
                          "id": "00000000-0000-4000-8000-000000000000",
                          "name": "<name>",
                          "environment": "<environment>",
                          "willCreate": false
                        },
                        "summary": "<summary>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "apply-monitoring-plan",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/begin-aws-connect": {
      "post": {
        "operationId": "beginAwsConnect",
        "summary": "Begin an AWS connection",
        "description": "Start connecting an AWS account: returns a one-click CloudFormation URL and an external ID. Give the user the URL to open and create the stack, then poll check-aws-registration with the external ID; once registered, call connect-aws.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "configured": {
                          "type": "boolean"
                        },
                        "externalId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "cloudFormationUrl": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "configured",
                        "externalId",
                        "cloudFormationUrl"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "configured": false,
                        "externalId": "<external_id>",
                        "cloudFormationUrl": "https://example.com",
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "begin-aws-connect",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/begin-oauth-connect": {
      "post": {
        "operationId": "beginOauthConnect",
        "summary": "Start connecting a provider with OAuth",
        "description": "Begin an OAuth connection and return a URL for the user to open. They approve in their browser; no API token is created or pasted. Give the user the URL, then poll check-oauth-connect with the returned `state` to find out when they are done — do not ask them to tell you.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "description": "Integration id, e.g. \"cloudflare\"."
                  },
                  "returnTo": {
                    "type": "string",
                    "description": "Path to return the user to afterwards; defaults to the integration screen."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach the resulting integration to, from list-stacks."
                  }
                },
                "required": [
                  "provider"
                ],
                "additionalProperties": false
              },
              "example": {
                "provider": "cloudflare",
                "returnTo": "replace_with_return_to",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "available": {
                          "type": "boolean"
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "state": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "pollWith": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "message": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "available",
                        "url",
                        "state",
                        "pollWith",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "available": false,
                        "url": "https://example.com",
                        "state": "<state>",
                        "pollWith": "<pollWith>",
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "begin-oauth-connect",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/check-aws-registration": {
      "post": {
        "operationId": "checkAwsRegistration",
        "summary": "Check AWS auto-registration",
        "description": "Check whether the CloudFormation stack from begin-aws-connect has reported its AWS account ID yet. Poll every few seconds after the user creates the stack; when status is 'registered', call connect-aws with the returned accountId.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalId": {
                    "type": "string"
                  }
                },
                "required": [
                  "externalId"
                ],
                "additionalProperties": false
              },
              "example": {
                "externalId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "registered",
                            "connected",
                            "not_found"
                          ]
                        },
                        "accountId": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "pending",
                        "accountId": "00000000-0000-4000-8000-000000000000",
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "check-aws-registration",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/check-oauth-connect": {
      "post": {
        "operationId": "checkOauthConnect",
        "summary": "Check an OAuth connection in progress",
        "description": "Check whether the user has finished approving the URL from begin-oauth-connect. Poll every few seconds using the `state` it returned. `pending` means keep waiting; `connected` is done; `failed` carries the reason; `expired` carries a fresh `url` to offer instead of starting over.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "description": "The `state` returned by begin-oauth-connect."
                  }
                },
                "required": [
                  "state"
                ],
                "additionalProperties": false
              },
              "example": {
                "state": "replace_with_state"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "connected",
                            "failed",
                            "expired",
                            "not_found"
                          ]
                        },
                        "provider": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "integrationId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "message": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "status",
                        "provider",
                        "integrationId",
                        "url",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "pending",
                        "provider": "cloudflare",
                        "integrationId": "00000000-0000-4000-8000-000000000000",
                        "url": "https://example.com",
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "check-oauth-connect",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-aws": {
      "post": {
        "operationId": "connectAws",
        "summary": "Connect an AWS account",
        "description": "Finish connecting AWS with the 12-digit account ID and the external ID from begin-aws-connect. Returns connected, pending (stack still creating — retry in ~30s), or error. Discovered AWS services are watched automatically.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accountId": {
                    "type": "string",
                    "description": "Your 12-digit AWS account ID."
                  },
                  "externalId": {
                    "type": "string",
                    "description": "The external ID from begin-aws-connect."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this AWS connection to; defaults to your default stack."
                  }
                },
                "required": [
                  "accountId",
                  "externalId"
                ],
                "additionalProperties": false
              },
              "example": {
                "accountId": "00000000-0000-4000-8000-000000000000",
                "externalId": "00000000-0000-4000-8000-000000000000",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "pending",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-aws",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-cloudflare": {
      "post": {
        "operationId": "connectCloudflare",
        "summary": "Connect Cloudflare",
        "description": "Connect Cloudflare with a read-only API token. Imports Workers, Pages projects, zones, R2 buckets, KV namespaces, D1 databases, Queues and Durable Object namespaces across every account the token reaches; pass watch:'all' to start watching them immediately, or follow up with set-watchlist.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "apiToken": {
                    "type": "string",
                    "description": "Cloudflare API token with read access. Create one at https://dash.cloudflare.com/profile/api-tokens. Beaam imports every Workers script, Pages project, zone, R2 bucket, KV namespace, D1 database, Queue and Durable Object namespace the token can see, across every account it reaches. Stored encrypted; only read endpoints are called."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from Cloudflare's OAuth callback. Supplied by Beaam's callback route; leave unset when connecting with an API token."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The matching single-use state value from Beaam's OAuth callback."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this Cloudflare connection to; defaults to your default stack."
                  },
                  "watch": {
                    "type": "string",
                    "enum": [
                      "all",
                      "none"
                    ],
                    "description": "Start watching the imported resources ('all') or none ('none', default). 'all' is all-or-nothing: if the estate does not fit your plan's watch limit, Beaam watches none and asks you to choose, rather than picking for you."
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "example": {
                "apiToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "watch": "all"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        },
                        "integrationId": {
                          "type": "string",
                          "description": "On a reconnect, the existing connection that was repaired in place."
                        },
                        "skipped": {
                          "type": "array",
                          "description": "Resources discovery could not read, each with the provider's own reason.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "resource": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "resource",
                              "reason"
                            ]
                          }
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25,
                        "integrationId": "00000000-0000-4000-8000-000000000000",
                        "skipped": [
                          {
                            "resource": "<resource>",
                            "reason": "<reason>"
                          }
                        ]
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-cloudflare",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-digitalocean": {
      "post": {
        "operationId": "connectDigitalocean",
        "summary": "Connect DigitalOcean",
        "description": "Watch a DigitalOcean account's resource health, Droplet pressure and backups, deployments, scaling, databases, Kubernetes, load balancers, and certificates within a bounded API budget.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accessToken": {
                    "type": "string",
                    "description": "DigitalOcean personal access token. Beaam imports the account's Droplets, load balancers, apps, managed databases, Kubernetes clusters, autoscale pools, and certificates. Read scope is enough. Stored encrypted. Omit when connecting over OAuth."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the DigitalOcean OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach these DigitalOcean resources to; defaults to your default stack."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "accessToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-digitalocean",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-hostinger": {
      "post": {
        "operationId": "connectHostinger",
        "summary": "Connect Hostinger",
        "description": "Watch a Hostinger account's VPS — suspended by Hostinger, stopped, or destroyed.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Hostinger OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "apiToken": {
                    "type": "string",
                    "description": "Hostinger API token from hPanel. Beaam imports every VPS the token can see and tracks each one's state — alerting immediately if Hostinger suspends it. Read access is enough. Stored encrypted."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach these VPS to; defaults to your default stack."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "apiToken": "replace_with_token",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-hostinger",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-http": {
      "post": {
        "operationId": "connectHttp",
        "summary": "Connect HTTP endpoint",
        "description": "Add a URL to monitor. Beaam will ping it every minute and alert if it goes down.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "URL to monitor, e.g. https://example.com"
                  },
                  "acceptableStatuses": {
                    "type": "string",
                    "description": "Healthy HTTP codes or ranges, e.g. 200-399,404. Defaults to 200-399."
                  },
                  "expectedBody": {
                    "type": "string",
                    "description": "Optional exact text that must appear in the response body."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this endpoint to; defaults to your default stack."
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false
              },
              "example": {
                "url": "https://example.com",
                "acceptableStatuses": "replace_with_acceptable_statuses",
                "expectedBody": "replace_with_expected_body",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-http",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-mcp": {
      "post": {
        "operationId": "connectMcp",
        "summary": "Connect MCP server",
        "description": "Add a remote MCP server to monitor. Beaam validates the initialize + tools/list handshake every minute and alerts if it breaks.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "transport": {
                    "type": "string",
                    "enum": [
                      "sse",
                      "streamable-http"
                    ]
                  },
                  "authType": {
                    "type": "string",
                    "enum": [
                      "none",
                      "bearer",
                      "basic",
                      "header"
                    ]
                  },
                  "authToken": {
                    "type": "string"
                  },
                  "authUsername": {
                    "type": "string"
                  },
                  "authPassword": {
                    "type": "string"
                  },
                  "authHeaderName": {
                    "type": "string"
                  },
                  "authHeaderValue": {
                    "type": "string"
                  },
                  "stackId": {
                    "type": "string"
                  }
                },
                "required": [
                  "url",
                  "transport",
                  "authType"
                ],
                "additionalProperties": false
              },
              "example": {
                "url": "https://example.com",
                "transport": "sse",
                "authType": "none",
                "authToken": "replace_with_token",
                "authUsername": "replace_with_auth_username",
                "authPassword": "replace_with_password",
                "authHeaderName": "replace_with_auth_header_name",
                "authHeaderValue": "replace_with_auth_header_value",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-mcp",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-mongodb": {
      "post": {
        "operationId": "connectMongodb",
        "summary": "Connect MongoDB Atlas",
        "description": "Connect MongoDB Atlas using a read-only service account (Client ID + Secret). Discovers your clusters; pass watch:'all' to start watching them immediately, or follow up with set-watchlist.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "description": "MongoDB Atlas service account Client ID (Organization → Access Manager → Applications)."
                  },
                  "clientSecret": {
                    "type": "string",
                    "description": "MongoDB Atlas service account Client Secret. Shown once at creation; stored encrypted."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this MongoDB Atlas connection to; defaults to your default stack."
                  },
                  "watch": {
                    "type": "string",
                    "enum": [
                      "all",
                      "none"
                    ],
                    "description": "Start watching the imported resources ('all') or none ('none', default). 'all' is all-or-nothing: if the estate does not fit your plan's watch limit, Beaam watches none and asks you to choose, rather than picking for you."
                  }
                },
                "required": [
                  "clientId",
                  "clientSecret"
                ],
                "additionalProperties": false
              },
              "example": {
                "clientId": "00000000-0000-4000-8000-000000000000",
                "clientSecret": "replace_with_secret",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "watch": "all"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-mongodb",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-neon": {
      "post": {
        "operationId": "connectNeon",
        "summary": "Connect Neon",
        "description": "Watch a Neon account's projects — disabled computes and failed control-plane operations.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "apiKey": {
                    "type": "string",
                    "description": "Neon API key. Beaam imports every project the key can see and watches each one's computes and control-plane operations. Read access is enough. Stored encrypted."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach these projects to; defaults to your default stack."
                  },
                  "watch": {
                    "type": "string",
                    "enum": [
                      "all",
                      "none"
                    ],
                    "description": "Start watching the imported resources ('all') or none ('none', default). 'all' is all-or-nothing: if the estate does not fit your plan's watch limit, Beaam watches none and asks you to choose, rather than picking for you."
                  }
                },
                "required": [
                  "apiKey"
                ],
                "additionalProperties": false
              },
              "example": {
                "apiKey": "replace_with_key",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "watch": "all"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-neon",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-netlify": {
      "post": {
        "operationId": "connectNetlify",
        "summary": "Connect Netlify",
        "description": "Watch a Netlify account's sites — deploys that failed, so a change you thought shipped is not silently missing.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accessToken": {
                    "type": "string",
                    "description": "Netlify personal access token. Beaam imports every site the token can see and watches each site's recent deploys for failures. Read access is enough. Stored encrypted. Omit when connecting over OAuth."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Netlify OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach these sites to; defaults to your default stack."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "accessToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-netlify",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-polar": {
      "post": {
        "operationId": "connectPolar",
        "summary": "Connect Polar",
        "description": "Watch a Polar organization's subscription payment health — how many subscriptions have stopped paying.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accessToken": {
                    "type": "string",
                    "description": "Polar Organization Access Token (polar_oat_…), created in your organization's settings with the read scopes listed by the Polar integration. Beaam watches revenue operations and webhook delivery health. Stored encrypted; only read endpoints are called. Omit when connecting over OAuth."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Polar OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this organization to; defaults to your default stack."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "accessToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-polar",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-resend": {
      "post": {
        "operationId": "connectResend",
        "summary": "Connect Resend",
        "description": "Watch a Resend account's send API failures, quota usage, domain DNS readiness, and delivery reputation.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Resend OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "apiKey": {
                    "type": "string",
                    "description": "Resend API key (re_…). Beaam reads account logs and each sending domain's deliverability and DNS readiness. Resend requires a Full access key for these read endpoints; Beaam never sends mail. Stored encrypted."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach these domains to; defaults to your default stack."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "apiKey": "replace_with_key",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-resend",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-sentry": {
      "post": {
        "operationId": "connectSentry",
        "summary": "Connect Sentry",
        "description": "Connect Sentry using an auth token with project:read and org:read scopes. Discovers all projects and returns connected / error.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "authToken": {
                    "type": "string",
                    "description": "Sentry auth token with project:read and org:read scopes. Omit when connecting over OAuth."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Sentry OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "baseUrl": {
                    "type": "string",
                    "description": "Sentry base URL for self-hosted instances (default: https://sentry.io)."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this Sentry connection to; defaults to your default stack."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "authToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "baseUrl": "https://example.com",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-sentry",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-stripe": {
      "post": {
        "operationId": "connectStripe",
        "summary": "Connect Stripe",
        "description": "Connect Stripe using a restricted key with read access to Account, Events, and Webhook Endpoints. Starts account, payment, billing, payout, fraud, and webhook monitoring immediately.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "secretKey": {
                    "type": "string",
                    "description": "Stripe restricted key (rk_live_... or rk_test_...) with read access to Account, Events, and Webhook Endpoints."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this Stripe connection to; defaults to your default stack."
                  }
                },
                "required": [
                  "secretKey"
                ],
                "additionalProperties": false
              },
              "example": {
                "secretKey": "replace_with_secret",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-stripe",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-supabase": {
      "post": {
        "operationId": "connectSupabase",
        "summary": "Connect Supabase",
        "description": "Connect Supabase with a personal access token. Imports every project in your organization; pass watch:'all' to start watching them immediately, or follow up with set-watchlist.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accessToken": {
                    "type": "string",
                    "description": "Supabase personal access token (sbp_…). Create one at https://supabase.com/dashboard/account/tokens. Beaam imports every project in the org. Stored encrypted. Omit when connecting over OAuth."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Supabase OAuth callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the authorization."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach this Supabase connection to; defaults to your default stack."
                  },
                  "watch": {
                    "type": "string",
                    "enum": [
                      "all",
                      "none"
                    ],
                    "description": "Start watching the imported resources ('all') or none ('none', default). 'all' is all-or-nothing: if the estate does not fit your plan's watch limit, Beaam watches none and asks you to choose, rather than picking for you."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "accessToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "watch": "all"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-supabase",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/connect-vercel": {
      "post": {
        "operationId": "connectVercel",
        "summary": "Connect Vercel",
        "description": "Watch a Vercel account's projects — production deploys that failed, without firing for preview builds.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accessToken": {
                    "type": "string",
                    "description": "Vercel access token. Beaam imports every project the token reaches — personal and every team — and watches production deploys for failures. Read access is enough. Stored encrypted."
                  },
                  "oauthCode": {
                    "type": "string",
                    "description": "Authorization code from the Vercel integration callback. Use begin-oauth-connect instead of calling this directly."
                  },
                  "oauthState": {
                    "type": "string",
                    "description": "The single-use state that began the Vercel authorization."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Stack to attach these projects to; defaults to your default stack."
                  },
                  "watch": {
                    "type": "string",
                    "enum": [
                      "all",
                      "none"
                    ],
                    "description": "Start watching the imported resources ('all') or none ('none', default). 'all' is all-or-nothing: if the estate does not fit your plan's watch limit, Beaam watches none and asks you to choose, rather than picking for you."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "accessToken": "replace_with_token",
                "oauthCode": "replace_with_oauth_code",
                "oauthState": "replace_with_oauth_state",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "watch": "all"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "discoveredCount": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "connected",
                        "message": "<message>",
                        "discoveredCount": 25
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "connect-vercel",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/create-stack": {
      "post": {
        "operationId": "createStack",
        "summary": "Create a stack",
        "description": "Create a stack — a group of services you think of together. Pass withIngestKey to also mint a one-time OTLP ingest key; otherwise the stack is grouping only and a key can be minted later.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Display name, e.g. 'Acme Production'."
                  },
                  "environment": {
                    "type": "string",
                    "description": "e.g. production / staging."
                  },
                  "withIngestKey": {
                    "type": "boolean",
                    "description": "Also mint an OTLP ingest key, returned once. Off by default — a stack is a grouping first, and telemetry ingest is opt-in."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "replace_with_name",
                "environment": "replace_with_environment",
                "withIngestKey": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "stack": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "environment": {
                              "type": "string"
                            }
                          }
                        },
                        "ingestKey": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ingest key, shown ONCE and never retrievable again. Null unless withIngestKey was set — which is the default, so a client must handle null."
                        }
                      },
                      "required": [
                        "stack",
                        "ingestKey"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "stack": {
                          "id": "00000000-0000-4000-8000-000000000000",
                          "name": "<name>",
                          "slug": "<slug>",
                          "environment": "<environment>"
                        },
                        "ingestKey": "<key>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "create-stack",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/delete-integration": {
      "post": {
        "operationId": "deleteIntegration",
        "summary": "Delete an integration",
        "description": "Remove an integration and everything associated with it — its services, history, incidents, alerts, and stored credentials. Irreversible.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "Integration id to remove."
                  }
                },
                "required": [
                  "integrationId"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "deletedServices": {
                          "type": "integer"
                        },
                        "leftBehind": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Anything Beaam created in the provider account that it could not remove, and how to remove it by hand."
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "deletedServices": 1,
                        "leftBehind": [
                          "<leftBehind>"
                        ]
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "delete-integration",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/delete-stack": {
      "post": {
        "operationId": "deleteStack",
        "summary": "Delete a stack",
        "description": "Delete an empty stack. Refuses while it still holds services or connections — move those first — and refuses to delete your only stack.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string",
                    "description": "The stack to delete."
                  }
                },
                "required": [
                  "stackId"
                ],
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "delete-stack",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-integration-catalog": {
      "post": {
        "operationId": "getIntegrationCatalog",
        "summary": "List everything Beaam can monitor",
        "description": "The public catalog of Beaam integrations — what each one watches, which signals can raise an incident, and what else is collected for context. Includes integrations on the roadmap (planned) and any temporarily withdrawn.",
        "tags": [
          "integrations"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "guidance": {
                          "type": "object",
                          "description": "How to gather evidence for the detect rules below. Read these sources; never read the ones listed under neverRead.",
                          "properties": {
                            "read": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "neverRead": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "notes": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "integrations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "category": {
                                "type": "string"
                              },
                              "blurb": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "available",
                                  "planned",
                                  "withdrawn"
                                ]
                              },
                              "detect": {
                                "type": "object",
                                "description": "How a project reveals it uses this provider. envVars are variable NAMES; never send values.",
                                "properties": {
                                  "files": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "dependencies": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "envVars": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "urlPatterns": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "cli": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                }
                              },
                              "withdrawnReason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "summary": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "alerts": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "label": {
                                      "type": "string"
                                    },
                                    "detail": {
                                      "type": "string"
                                    }
                                  }
                                }
                              },
                              "collected": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "guidance",
                        "integrations"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "guidance": {
                          "read": [
                            "<read>"
                          ],
                          "neverRead": [
                            "<neverRead>"
                          ],
                          "notes": [
                            "<note>"
                          ]
                        },
                        "integrations": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "label": "<label>",
                            "category": "<category>",
                            "blurb": "<blurb>",
                            "status": "available",
                            "detect": {
                              "files": [
                                "<file>"
                              ],
                              "dependencies": [
                                "<dependencie>"
                              ],
                              "envVars": [
                                "<envVar>"
                              ],
                              "urlPatterns": [
                                "<urlPattern>"
                              ],
                              "cli": "<cli>"
                            },
                            "withdrawnReason": "<withdrawnReason>",
                            "summary": "<summary>",
                            "alerts": [
                              {
                                "label": "<label>",
                                "detail": "<detail>"
                              }
                            ],
                            "collected": [
                              "<collected>"
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-integration-catalog",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-connections": {
      "post": {
        "operationId": "listConnections",
        "summary": "List connections",
        "description": "Return the user's connected integration instances (accounts) with each one's status, collection mode, check interval, and whether it needs reconnecting. Filter by provider or stack.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "description": "Only return connections for this provider (e.g. 'cloudflare')."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Only return connections in this stack."
                  },
                  "activeOnly": {
                    "type": "boolean",
                    "description": "Only return active connections (default false)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "provider": "cloudflare",
                "stackId": "00000000-0000-4000-8000-000000000000",
                "activeOnly": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "connections": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "display_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "status": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "collector_mode": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "poll_interval_seconds": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "needs_reconnect": {
                                "type": "boolean"
                              },
                              "connected_by_email": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "connected_by_you": {
                                "type": "boolean"
                              },
                              "provider_identity": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "reconnect_reason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "connections"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "connections": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "type": "<type>",
                            "display_name": "<display_name>",
                            "status": "<status>",
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "collector_mode": "<collector_mode>",
                            "poll_interval_seconds": 1,
                            "needs_reconnect": false,
                            "connected_by_email": "<connected_by_email>",
                            "connected_by_you": false,
                            "provider_identity": "<provider_identity>",
                            "reconnect_reason": "<reconnect_reason>"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-connections",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-integrations": {
      "post": {
        "operationId": "listIntegrations",
        "summary": "List integrations",
        "description": "Return the catalog of integrations to choose from — available ones (connectable now, like Cloudflare), planned ones, and any temporarily withdrawn — with whether the signed-in user has each connected.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string",
                    "description": "Count connections within this stack only."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "integrations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "category": {
                                "type": "string"
                              },
                              "blurb": {
                                "type": "string"
                              },
                              "icon": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "available",
                                  "planned",
                                  "withdrawn"
                                ]
                              },
                              "connect": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "connected": {
                                "type": "boolean"
                              },
                              "connectedCount": {
                                "type": "integer"
                              },
                              "watchedCount": {
                                "type": "integer"
                              },
                              "attentionCount": {
                                "type": "integer"
                              },
                              "needsReconnectCount": {
                                "type": "integer"
                              },
                              "votes": {
                                "type": "integer",
                                "description": "Votes from your organization for a planned integration; 0 for available ones, which are not voteable. Org-scoped, never a cross-customer tally."
                              },
                              "youVoted": {
                                "type": "boolean",
                                "description": "Whether the calling user's own vote stands."
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "integrations"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "integrations": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "label": "<label>",
                            "category": "<category>",
                            "blurb": "<blurb>",
                            "icon": "<icon>",
                            "status": "available",
                            "connect": "<connect>",
                            "connected": false,
                            "connectedCount": 25,
                            "watchedCount": 25,
                            "attentionCount": 25,
                            "needsReconnectCount": 25,
                            "votes": 1,
                            "youVoted": false
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-integrations",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-planned-connections": {
      "post": {
        "operationId": "listPlannedConnections",
        "summary": "List planned connections not yet made",
        "description": "List the providers an approved monitoring plan proposed that are still not connected. Read-only; use next-connection to actually walk through them.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "outstanding": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "provider": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "provider",
                              "label"
                            ]
                          }
                        },
                        "count": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "outstanding",
                        "count"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "outstanding": [
                          {
                            "provider": "cloudflare",
                            "label": "<label>"
                          }
                        ],
                        "count": 25
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-planned-connections",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-stacks": {
      "post": {
        "operationId": "listStacks",
        "summary": "List stacks",
        "description": "Return the signed-in user's stacks — each one a logical app + environment that integrations attach to and telemetry is grouped under.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "stacks": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "environment": {
                                "type": "string"
                              },
                              "ingest_key_prefix": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "last_ingest_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Last successful OTLP ingest; null if this stack has never pushed telemetry."
                              },
                              "ingest_silent_since": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Set while telemetry has gone silent (no OTLP past the expected cadence)."
                              },
                              "public_status_enabled": {
                                "type": "boolean"
                              },
                              "public_status_slug": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "public_status_show_service_names": {
                                "type": "boolean"
                              },
                              "public_status_show_incidents": {
                                "type": "boolean"
                              },
                              "service_count": {
                                "type": "number"
                              },
                              "otel_registration": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "registered",
                                  "pending",
                                  "blocked_by_plan",
                                  null
                                ],
                                "description": "For a stack that has received OpenTelemetry: whether its services are being registered, or held back because the organization is at its plan's integration limit."
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "stacks"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "stacks": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "name": "<name>",
                            "slug": "<slug>",
                            "environment": "<environment>",
                            "ingest_key_prefix": "<ingest_key_prefix>",
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "last_ingest_at": "2026-01-01T00:00:00.000Z",
                            "ingest_silent_since": "2026-01-01T00:00:00.000Z",
                            "public_status_enabled": false,
                            "public_status_slug": "<public_status_slug>",
                            "public_status_show_service_names": false,
                            "public_status_show_incidents": false,
                            "service_count": 25,
                            "otel_registration": "registered"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-stacks",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/next-connection": {
      "post": {
        "operationId": "nextConnection",
        "summary": "Get the next thing to connect",
        "description": "The next provider from an approved plan that is not connected yet, with a one-click URL. Call after apply-monitoring-plan, then again each time check-oauth-connect reports connected, until status is 'done'. Pass `dismiss` only if the user says they do not want that provider.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dismiss": {
                    "type": "string",
                    "description": "Provider id to stop asking about, e.g. \"sentry\". Use only when the user says they do not want it."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Target stack returned by apply-monitoring-plan."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "dismiss": "replace_with_dismiss",
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "done"
                          ]
                        },
                        "provider": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "label": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "state": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "pollWith": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "capability": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "stackId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "remaining": {
                          "type": "number"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "provider",
                        "label",
                        "url",
                        "state",
                        "pollWith",
                        "capability",
                        "stackId",
                        "remaining",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ready",
                        "provider": "cloudflare",
                        "label": "<label>",
                        "url": "https://example.com",
                        "state": "<state>",
                        "pollWith": "<pollWith>",
                        "capability": "<capability>",
                        "stackId": "00000000-0000-4000-8000-000000000000",
                        "remaining": 1,
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "next-connection",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/plan-monitoring": {
      "post": {
        "operationId": "planMonitoring",
        "summary": "Plan what Beaam would monitor in a project",
        "description": "Build a monitoring plan from safe project evidence: repo paths, dependencies, env-var names, public URLs, API hosts, and authenticated CLI checks. Returns new connections, existing coverage, unsupported items, and questions to answer. Records a short-lived plan but connects nothing.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "evidence": {
                    "type": "object",
                    "description": "What the project reveals about itself. Gather with get-integration-catalog's `detect` rules. Send env var NAMES only — never values, and never read a credential file.",
                    "properties": {
                      "files": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Normalized repository-relative paths, not only basenames."
                      },
                      "dependencies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "envVars": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "urls": {
                        "type": "array",
                        "maxItems": 10,
                        "items": {
                          "type": "string"
                        },
                        "description": "Candidate public app URLs. At most 10; each is safety-checked and contacted with a bounded HEAD request before it can enter the plan."
                      },
                      "apiHosts": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Hostnames the source calls, e.g. api.stripe.com. Match against each integration's detect.urlPatterns."
                      },
                      "cli": {
                        "type": "array",
                        "description": "Results of exact detect.cli commands from get-integration-catalog. Send only the command and authenticated boolean, never command output.",
                        "items": {
                          "type": "object",
                          "properties": {
                            "command": {
                              "type": "string"
                            },
                            "authenticated": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "command",
                            "authenticated"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "providerAccounts": {
                        "type": "array",
                        "description": "Non-secret provider account/org identities from deploy configuration or an exact identity command. Never send command output, tokens, or credential-file contents.",
                        "items": {
                          "type": "object",
                          "properties": {
                            "provider": {
                              "type": "string",
                              "description": "Integration id, e.g. cloudflare."
                            },
                            "accountKey": {
                              "type": "string",
                              "description": "Provider-native account or organization id; this must not be a secret."
                            }
                          },
                          "required": [
                            "provider",
                            "accountKey"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "stackId": {
                        "type": "string",
                        "description": "Existing Beaam stack selected by the user, from list-stacks."
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "evidence"
                ],
                "additionalProperties": false
              },
              "example": {
                "evidence": {
                  "files": [
                    "replace_with_file"
                  ],
                  "dependencies": [
                    "replace_with_dependencie"
                  ],
                  "envVars": [
                    "replace_with_env_var"
                  ],
                  "urls": [
                    "https://example.com"
                  ],
                  "apiHosts": [
                    "replace_with_api_host"
                  ],
                  "cli": [
                    {
                      "command": "replace_with_command",
                      "authenticated": false
                    }
                  ],
                  "providerAccounts": [
                    {
                      "provider": "cloudflare",
                      "accountKey": "replace_with_key"
                    }
                  ],
                  "stackId": "00000000-0000-4000-8000-000000000000"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "planId": {
                          "type": "string"
                        },
                        "alreadyConnected": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "connect": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "provider": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "method": {
                                "type": "string",
                                "enum": [
                                  "oauth",
                                  "token",
                                  "url"
                                ]
                              },
                              "capability": {
                                "type": "string"
                              },
                              "evidence": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "confidence": {
                                "type": "string",
                                "enum": [
                                  "strong",
                                  "weak"
                                ]
                              },
                              "baselineIntegrationIds": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "forceNew": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "provider",
                              "label",
                              "method",
                              "capability",
                              "evidence",
                              "confidence",
                              "baselineIntegrationIds"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "unconfirmed": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "provider": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "method": {
                                "type": "string",
                                "enum": [
                                  "oauth",
                                  "token",
                                  "url"
                                ]
                              },
                              "capability": {
                                "type": "string"
                              },
                              "evidence": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "confidence": {
                                "type": "string",
                                "enum": [
                                  "strong",
                                  "weak"
                                ]
                              },
                              "baselineIntegrationIds": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "forceNew": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "provider",
                              "label",
                              "method",
                              "capability",
                              "evidence",
                              "confidence",
                              "baselineIntegrationIds"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "accountDecisions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "questionId": {
                                "type": "string"
                              },
                              "provider": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "providerConfirmationRequired": {
                                "type": "boolean"
                              },
                              "canConnectNew": {
                                "type": "boolean"
                              },
                              "step": {
                                "type": "object",
                                "properties": {
                                  "provider": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "method": {
                                    "type": "string",
                                    "enum": [
                                      "oauth",
                                      "token",
                                      "url"
                                    ]
                                  },
                                  "capability": {
                                    "type": "string"
                                  },
                                  "evidence": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "confidence": {
                                    "type": "string",
                                    "enum": [
                                      "strong",
                                      "weak"
                                    ]
                                  },
                                  "baselineIntegrationIds": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "forceNew": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "provider",
                                  "label",
                                  "method",
                                  "capability",
                                  "evidence",
                                  "confidence",
                                  "baselineIntegrationIds"
                                ],
                                "additionalProperties": false
                              },
                              "existing": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "integrationId": {
                                      "type": "string"
                                    },
                                    "label": {
                                      "type": "string"
                                    },
                                    "accountKey": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "integrationId",
                                    "label",
                                    "accountKey"
                                  ],
                                  "additionalProperties": false
                                }
                              }
                            },
                            "required": [
                              "questionId",
                              "provider",
                              "label",
                              "providerConfirmationRequired",
                              "canConnectNew",
                              "step",
                              "existing"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "watch": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "url": {
                                "type": "string"
                              },
                              "capability": {
                                "type": "string"
                              },
                              "verification": {
                                "type": "object",
                                "properties": {
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "reachable",
                                      "unreachable"
                                    ]
                                  },
                                  "httpStatus": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "responseTimeMs": {
                                    "type": "number"
                                  },
                                  "detail": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "status",
                                  "httpStatus",
                                  "responseTimeMs",
                                  "detail"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "url",
                              "capability",
                              "verification"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "targetStack": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "id": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "name": {
                              "type": "string"
                            },
                            "environment": {
                              "type": "string"
                            },
                            "willCreate": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "environment",
                            "willCreate"
                          ],
                          "additionalProperties": false
                        },
                        "questions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ask": {
                                "type": "string"
                              },
                              "options": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "value": {
                                      "type": "string"
                                    },
                                    "label": {
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "value",
                                    "label"
                                  ],
                                  "additionalProperties": false
                                }
                              },
                              "why": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "ask",
                              "options",
                              "why"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "cannot": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "name",
                              "reason"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "tier": {
                          "type": "object",
                          "properties": {
                            "integrationsRemaining": {
                              "type": "number"
                            },
                            "watchedRemaining": {
                              "type": "number"
                            },
                            "atLimit": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "integrationsRemaining",
                            "watchedRemaining",
                            "atLimit"
                          ],
                          "additionalProperties": false
                        },
                        "summary": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "planId",
                        "alreadyConnected",
                        "connect",
                        "unconfirmed",
                        "accountDecisions",
                        "watch",
                        "targetStack",
                        "questions",
                        "cannot",
                        "tier",
                        "summary"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "planId": "00000000-0000-4000-8000-000000000000",
                        "alreadyConnected": [
                          "<alreadyConnected>"
                        ],
                        "connect": [
                          {
                            "provider": "cloudflare",
                            "label": "<label>",
                            "method": "oauth",
                            "capability": "<capability>",
                            "evidence": [
                              "<evidence>"
                            ],
                            "confidence": "strong",
                            "baselineIntegrationIds": [
                              "00000000-0000-4000-8000-000000000000"
                            ],
                            "forceNew": false
                          }
                        ],
                        "unconfirmed": [
                          {
                            "provider": "cloudflare",
                            "label": "<label>",
                            "method": "oauth",
                            "capability": "<capability>",
                            "evidence": [
                              "<evidence>"
                            ],
                            "confidence": "strong",
                            "baselineIntegrationIds": [
                              "00000000-0000-4000-8000-000000000000"
                            ],
                            "forceNew": false
                          }
                        ],
                        "accountDecisions": [
                          {
                            "questionId": "provider-account:cloudflare",
                            "provider": "cloudflare",
                            "label": "<label>",
                            "providerConfirmationRequired": false,
                            "canConnectNew": false,
                            "step": {
                              "provider": "cloudflare",
                              "label": "<label>",
                              "method": "oauth",
                              "capability": "<capability>",
                              "evidence": [
                                "<evidence>"
                              ],
                              "confidence": "strong",
                              "baselineIntegrationIds": [
                                "00000000-0000-4000-8000-000000000000"
                              ],
                              "forceNew": false
                            },
                            "existing": [
                              {
                                "integrationId": "00000000-0000-4000-8000-000000000000",
                                "label": "<label>",
                                "accountKey": "<key>"
                              }
                            ]
                          }
                        ],
                        "watch": [
                          {
                            "url": "https://example.com",
                            "capability": "<capability>",
                            "verification": {
                              "status": "reachable",
                              "httpStatus": 1,
                              "responseTimeMs": 1,
                              "detail": "<detail>"
                            }
                          }
                        ],
                        "targetStack": {
                          "id": "00000000-0000-4000-8000-000000000000",
                          "name": "<name>",
                          "environment": "<environment>",
                          "willCreate": false
                        },
                        "questions": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "ask": "<ask>",
                            "options": [
                              {
                                "value": "<value>",
                                "label": "<label>"
                              }
                            ],
                            "why": "<why>"
                          }
                        ],
                        "cannot": [
                          {
                            "name": "<name>",
                            "reason": "<reason>"
                          }
                        ],
                        "tier": {
                          "integrationsRemaining": 1,
                          "watchedRemaining": 1,
                          "atLimit": false
                        },
                        "summary": "<summary>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "plan-monitoring",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/rediscover-integration": {
      "post": {
        "operationId": "rediscoverIntegration",
        "summary": "Re-discover a connection now",
        "description": "Look for resources created since this connection was last checked, and add any new ones as unwatched services.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "The connection to re-discover."
                  }
                },
                "required": [
                  "integrationId"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "added": {
                          "type": "integer"
                        },
                        "refreshed": {
                          "type": "integer"
                        },
                        "missing": {
                          "type": "integer"
                        },
                        "discovered": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "added": 1,
                        "refreshed": 1,
                        "missing": 1,
                        "discovered": 1
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "rediscover-integration",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/remove-missing-services": {
      "post": {
        "operationId": "removeMissingServices",
        "summary": "Remove services that no longer exist",
        "description": "Permanently remove services that the provider no longer has, along with their history. Only affects services already detected as missing by re-discovery.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "Only remove missing services from this integration. Omit to remove all of them."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "removed": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status",
                        "message",
                        "removed"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "removed": 1
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "remove-missing-services",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/rename-stack": {
      "post": {
        "operationId": "renameStack",
        "summary": "Rename a stack",
        "description": "Change a stack's display name. Its slug — the OTel service.namespace your exporters send to — is deliberately left alone.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string",
                    "description": "The stack to rename."
                  },
                  "name": {
                    "type": "string",
                    "description": "New display name."
                  }
                },
                "required": [
                  "stackId",
                  "name"
                ],
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000",
                "name": "replace_with_name"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "name": "<name>",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "rename-stack",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/resolve-oauth-connect": {
      "post": {
        "operationId": "resolveOauthConnect",
        "summary": "Resolve an OAuth connect link",
        "description": "Turn a connect state into the provider's consent URL, after checking the link belongs to you and has not expired or been used.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "description": "The connect state from begin-oauth-connect. Single-use and short-lived."
                  }
                },
                "required": [
                  "state"
                ],
                "additionalProperties": false
              },
              "example": {
                "state": "replace_with_state"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "reason": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "ready",
                        "url",
                        "reason",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "ready": false,
                        "url": "https://example.com",
                        "reason": "<reason>",
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "resolve-oauth-connect",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/revoke-ingest-key": {
      "post": {
        "operationId": "revokeIngestKey",
        "summary": "Revoke a stack's ingest key",
        "description": "Disable a stack's OTLP ingest key immediately; the stack stops accepting telemetry until you rotate to a new key.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string",
                    "description": "The stack whose ingest key to revoke."
                  }
                },
                "required": [
                  "stackId"
                ],
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "revoke-ingest-key",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/rotate-ingest-key": {
      "post": {
        "operationId": "rotateIngestKey",
        "summary": "Rotate a stack's ingest key",
        "description": "Generate a new OTLP ingest key for a stack and invalidate the old one. Returns the new key once.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string",
                    "description": "The stack whose ingest key to rotate."
                  }
                },
                "required": [
                  "stackId"
                ],
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "ingestKey": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "ingestKey": "<key>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "rotate-ingest-key",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/set-collector-mode": {
      "post": {
        "operationId": "setCollectorMode",
        "summary": "Set collection mode",
        "description": "Switch an integration between pull (scheduled polling) and push (real-time metric stream). Switching to push rotates and returns a one-time stack ingest key.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "Integration to reconfigure."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "pull",
                      "push"
                    ],
                    "description": "pull = Beaam polls on a schedule; push = real-time metric stream into Beaam ingest."
                  }
                },
                "required": [
                  "integrationId",
                  "mode"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000",
                "mode": "pull"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "mode": {
                          "type": "string",
                          "enum": [
                            "pull",
                            "push"
                          ]
                        },
                        "ingestKey": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "mode": "pull",
                        "ingestKey": "<key>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-collector-mode",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-service-stack": {
      "post": {
        "operationId": "setServiceStack",
        "summary": "Move services to a stack",
        "description": "Move one or more services into a stack, so the list groups by the application they belong to rather than by the account they were discovered in. Services whose telemetry you push yourself get their stack from the ingest key and can't be moved here.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The service ids to move."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "The stack to move them into."
                  }
                },
                "required": [
                  "serviceIds",
                  "stackId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceIds": [
                  "00000000-0000-4000-8000-000000000000"
                ],
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "moved": {
                          "type": "integer"
                        },
                        "skipped": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "displayName": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            }
                          },
                          "description": "Services deliberately not moved, each with a reason."
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "moved",
                        "skipped"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "moved": 1,
                        "skipped": [
                          {
                            "serviceId": "00000000-0000-4000-8000-000000000000",
                            "displayName": "<displayName>",
                            "reason": "<reason>"
                          }
                        ],
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-service-stack",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-watchlist": {
      "post": {
        "operationId": "setWatchlist",
        "summary": "Set the watchlist",
        "description": "Choose which discovered services Beaam watches for an integration. Pass the integration id and the service ids to watch; the rest are unwatched.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string"
                  },
                  "serviceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The service ids to watch; all others are unwatched."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "If set, assert the integration belongs to this stack."
                  }
                },
                "required": [
                  "integrationId"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000",
                "serviceIds": [
                  "00000000-0000-4000-8000-000000000000"
                ],
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "watchedCount": {
                          "type": "integer"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "watchedCount",
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "watchedCount": 25,
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-watchlist",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/suggest-http-checks": {
      "post": {
        "operationId": "suggestHttpChecks",
        "summary": "Suggest HTTP checks for deployed sites",
        "description": "List watched sites whose provider only reports deploys (for example Netlify or Cloudflare Pages), with the URL to add as an HTTP check so Beaam also notices when the site stops answering.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "description": "Only suggest for this provider's services, e.g. netlify."
                  },
                  "serviceId": {
                    "type": "string",
                    "description": "Only suggest for this one service."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "provider": "cloudflare",
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "suggestions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "serviceName": {
                                "type": "string"
                              },
                              "provider": {
                                "type": "string"
                              },
                              "providerLabel": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "reason": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "suggestions": [
                          {
                            "serviceId": "00000000-0000-4000-8000-000000000000",
                            "serviceName": "<serviceName>",
                            "provider": "cloudflare",
                            "providerLabel": "<providerLabel>",
                            "url": "https://example.com",
                            "reason": "<reason>"
                          }
                        ],
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "suggest-http-checks",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/update-integration-settings": {
      "post": {
        "operationId": "updateIntegrationSettings",
        "summary": "Update integration settings",
        "description": "Edit an integration's friendly name and/or its check interval (seconds). Invalid values are ignored.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "Integration to update."
                  },
                  "displayName": {
                    "type": "string",
                    "description": "Friendly name (trimmed, max 80 chars)."
                  },
                  "pollIntervalSeconds": {
                    "type": "integer",
                    "description": "Check cadence in seconds (15–3600)."
                  }
                },
                "required": [
                  "integrationId"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000",
                "displayName": "replace_with_display_name",
                "pollIntervalSeconds": 1
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "updated": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "updated": 1
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "update-integration-settings",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/vote-integration": {
      "post": {
        "operationId": "voteIntegration",
        "summary": "Vote for an integration",
        "description": "Vote for an integration Beaam has not built yet, or withdraw a vote. Tells the roadmap what to build next.",
        "tags": [
          "integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "description": "The planned integration to vote for, e.g. 'firebase' or 'railway'. Use list-integrations to see what is on the roadmap."
                  },
                  "vote": {
                    "type": "boolean",
                    "description": "True to vote (default); false to withdraw a vote you already cast."
                  }
                },
                "required": [
                  "provider"
                ],
                "additionalProperties": false
              },
              "example": {
                "provider": "cloudflare",
                "vote": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "provider": {
                          "type": "string"
                        },
                        "voted": {
                          "type": "boolean"
                        },
                        "votes": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "provider",
                        "voted",
                        "votes",
                        "message"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": "cloudflare",
                        "voted": false,
                        "votes": 1,
                        "message": "<message>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "vote-integration",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/check-coverage": {
      "post": {
        "operationId": "checkCoverage",
        "summary": "Check monitoring coverage",
        "description": "Given components found in a repository, report which are already watched by Beaam and which are not — with the exact call that would start watching each gap.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "candidates": {
                    "type": "array",
                    "description": "Components found locally that may need monitoring. Each is { kind, name, url?, source? }. Detection happens on the caller's machine; this capability only judges coverage.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "description": "http | worker | service | container"
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "kind",
                        "name"
                      ]
                    }
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Limit the comparison to one stack; defaults to every watched service."
                  }
                },
                "required": [
                  "candidates"
                ],
                "additionalProperties": false
              },
              "example": {
                "candidates": [
                  {
                    "kind": "replace_with_kind",
                    "name": "replace_with_name",
                    "url": "https://example.com",
                    "source": "replace_with_source"
                  }
                ],
                "stackId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "checked": {
                          "type": "integer"
                        },
                        "covered": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "gaps": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "atLimit": {
                          "type": "boolean"
                        },
                        "limitMessage": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "checked",
                        "covered",
                        "gaps",
                        "atLimit",
                        "limitMessage"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "checked": 1,
                        "covered": [
                          {}
                        ],
                        "gaps": [
                          {}
                        ],
                        "atLimit": false,
                        "limitMessage": "<limitMessage>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "check-coverage",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/detection-stats": {
      "post": {
        "operationId": "detectionStats",
        "summary": "Detection stats",
        "description": "True-positive / false-alarm counts, incident and suppression totals — how well Beaam is deciding what's worth your attention.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "alertsSent": {
                          "type": "integer"
                        },
                        "confirmedReal": {
                          "type": "integer"
                        },
                        "falseAlarms": {
                          "type": "integer"
                        },
                        "unreviewed": {
                          "type": "integer"
                        },
                        "incidents": {
                          "type": "integer"
                        },
                        "openIncidents": {
                          "type": "integer"
                        },
                        "suppressions": {
                          "type": "integer"
                        },
                        "falseAlarmRate": {
                          "type": [
                            "number",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "alertsSent",
                        "confirmedReal",
                        "falseAlarms",
                        "unreviewed",
                        "incidents",
                        "openIncidents",
                        "suppressions",
                        "falseAlarmRate"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "alertsSent": 1,
                        "confirmedReal": 1,
                        "falseAlarms": 1,
                        "unreviewed": 1,
                        "incidents": 1,
                        "openIncidents": 1,
                        "suppressions": 1,
                        "falseAlarmRate": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "detection-stats",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/explain-incident": {
      "post": {
        "operationId": "explainIncident",
        "summary": "Explain an incident",
        "description": "Explain why an incident happened in one sentence — the correlated services, learned lead/lag history, and any control-plane change (deploy, scaling, config) that preceded the failure. Uses AI narration only if your organization has enabled it; otherwise returns the same evidence deterministically.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "incidentId": {
                    "type": "string",
                    "description": "The incident to explain."
                  }
                },
                "required": [
                  "incidentId"
                ],
                "additionalProperties": false
              },
              "example": {
                "incidentId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "incidentId": {
                          "type": "string"
                        },
                        "service": {
                          "type": "string"
                        },
                        "verdict": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "deterministic",
                            "ai"
                          ]
                        },
                        "narrationUnavailable": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "evidenceUnavailable": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "evidenceSource": {
                          "type": "string",
                          "enum": [
                            "snapshot",
                            "recomputed"
                          ]
                        },
                        "evidenceAsOf": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "triggers": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object"
                          }
                        },
                        "confidence": {
                          "type": "object",
                          "properties": {
                            "change": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "enum": [
                                "high",
                                "medium",
                                "low",
                                null
                              ]
                            },
                            "group": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "enum": [
                                "high",
                                "medium",
                                "low",
                                null
                              ]
                            }
                          }
                        }
                      },
                      "required": [
                        "incidentId",
                        "service",
                        "verdict",
                        "source",
                        "narrationUnavailable",
                        "evidenceUnavailable",
                        "evidenceSource",
                        "evidenceAsOf",
                        "triggers",
                        "confidence"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "incidentId": "00000000-0000-4000-8000-000000000000",
                        "service": "<service>",
                        "verdict": "<verdict>",
                        "source": "deterministic",
                        "narrationUnavailable": "<narrationUnavailable>",
                        "evidenceUnavailable": [
                          "<evidenceUnavailable>"
                        ],
                        "evidenceSource": "snapshot",
                        "evidenceAsOf": "<evidenceAsOf>",
                        "triggers": [
                          {}
                        ],
                        "confidence": {
                          "change": "high",
                          "group": "high"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "explain-incident",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-collector-health": {
      "post": {
        "operationId": "getCollectorHealth",
        "summary": "Get collector health",
        "description": "Return collector health for the user's integrations — whether Beaam is successfully collecting, when it last succeeded, and the last error.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Limit to these integration ids; omit for all of the user's."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "integrationIds": [
                  "00000000-0000-4000-8000-000000000000"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "health": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "integration_id": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "last_ok_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "last_error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "health"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "health": [
                          {
                            "integration_id": "00000000-0000-4000-8000-000000000000",
                            "status": "<status>",
                            "last_ok_at": "2026-01-01T00:00:00.000Z",
                            "last_error": "<last_error>"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-collector-health",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-dashboard-revision": {
      "post": {
        "operationId": "getDashboardRevision",
        "summary": "Get a dashboard revision",
        "description": "Return a compact change cursor for one or more live dashboard scopes, without returning or modifying monitored data.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "revisionKeys": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 12,
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "revisionKeys"
                ],
                "additionalProperties": false
              },
              "example": {
                "revisionKeys": [
                  "replace_with_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "signature": {
                          "type": "string"
                        },
                        "freshnessSignature": {
                          "type": "string"
                        },
                        "checkedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "signature",
                        "freshnessSignature",
                        "checkedAt"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "signature": "<signature>",
                        "freshnessSignature": "<freshnessSignature>",
                        "checkedAt": "2026-01-01T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-dashboard-revision",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-health-grid": {
      "post": {
        "operationId": "getHealthGrid",
        "summary": "Get the health heatmap",
        "description": "Return per-service health buckets across a window for every watched service of a connection — the heatmap view, ordered worst-first. Shows whether services failed together, which the exception view cannot.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "The connection to chart."
                  },
                  "from": {
                    "type": "string",
                    "description": "ISO start of the window."
                  },
                  "to": {
                    "type": "string",
                    "description": "ISO end of the window."
                  },
                  "buckets": {
                    "type": "integer",
                    "description": "Columns across the window (max 168)."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max service rows, worst first (max 40)."
                  }
                },
                "required": [
                  "integrationId"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000",
                "from": "2026-01-01T00:00:00.000Z",
                "to": "2026-01-01T00:00:00.000Z",
                "buckets": 25,
                "limit": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "bucketCount": {
                          "type": "integer"
                        },
                        "rows": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "omitted": {
                          "type": "integer"
                        },
                        "withoutData": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "bucketCount",
                        "rows",
                        "omitted",
                        "withoutData"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "from": "2026-01-01T00:00:00.000Z",
                        "to": "2026-01-01T00:00:00.000Z",
                        "bucketCount": 25,
                        "rows": [
                          {}
                        ],
                        "omitted": 1,
                        "withoutData": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-health-grid",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-health-timeline": {
      "post": {
        "operationId": "getHealthTimeline",
        "summary": "Get an integration's health timeline",
        "description": "Summarize an integration's health over a time window (up to 7 days): worst-state timeline buckets, plus the events inside the window — state changes, alerts sent, and newly discovered services.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "The connection to summarize."
                  },
                  "window": {
                    "type": "string",
                    "enum": [
                      "1h",
                      "6h",
                      "24h",
                      "7d"
                    ],
                    "description": "Relative window, e.g. the last 24h. Ignored when from/to are given."
                  },
                  "from": {
                    "type": "string",
                    "description": "Window start (ISO 8601). Default: 6 hours ago."
                  },
                  "to": {
                    "type": "string",
                    "description": "Window end (ISO 8601). Default: now."
                  },
                  "buckets": {
                    "type": "integer",
                    "description": "Timeline resolution (default 72, max 200)."
                  }
                },
                "required": [
                  "integrationId"
                ],
                "additionalProperties": false
              },
              "example": {
                "integrationId": "00000000-0000-4000-8000-000000000000",
                "window": "1h",
                "from": "2026-01-01T00:00:00.000Z",
                "to": "2026-01-01T00:00:00.000Z",
                "buckets": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "serviceCount": {
                          "type": "integer"
                        },
                        "bucketCount": {
                          "type": "integer"
                        },
                        "buckets": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "lanes": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "steadyCount": {
                          "type": "integer"
                        },
                        "awaitingCount": {
                          "type": "integer"
                        },
                        "lanesOmitted": {
                          "type": "integer"
                        },
                        "minimap": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "minimapFrom": {
                          "type": "string"
                        },
                        "events": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "serviceCount",
                        "bucketCount",
                        "buckets",
                        "lanes",
                        "steadyCount",
                        "awaitingCount",
                        "lanesOmitted",
                        "minimap",
                        "minimapFrom",
                        "events"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "from": "2026-01-01T00:00:00.000Z",
                        "to": "2026-01-01T00:00:00.000Z",
                        "serviceCount": 25,
                        "bucketCount": 25,
                        "buckets": [
                          {}
                        ],
                        "lanes": [
                          {}
                        ],
                        "steadyCount": 25,
                        "awaitingCount": 25,
                        "lanesOmitted": 1,
                        "minimap": [
                          {}
                        ],
                        "minimapFrom": "<minimapFrom>",
                        "events": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-health-timeline",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-ingest-stats": {
      "post": {
        "operationId": "getIngestStats",
        "summary": "Get ingest stats",
        "description": "Return OTLP ingest volume (requests, datapoints, bytes) per stack over a look-back window.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "windowHours": {
                    "type": "number",
                    "description": "Look-back window in hours (default 24, max 720)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "windowHours": 1
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "windowHours": {
                          "type": "number"
                        },
                        "perStack": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "stackId": {
                                "type": "string"
                              },
                              "requests": {
                                "type": "number"
                              },
                              "rows": {
                                "type": "number"
                              },
                              "bytes": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "totals": {
                          "type": "object",
                          "properties": {
                            "requests": {
                              "type": "number"
                            },
                            "rows": {
                              "type": "number"
                            },
                            "bytes": {
                              "type": "number"
                            }
                          }
                        }
                      },
                      "required": [
                        "windowHours",
                        "perStack",
                        "totals"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "windowHours": 1,
                        "perStack": [
                          {
                            "stackId": "00000000-0000-4000-8000-000000000000",
                            "requests": 1,
                            "rows": 1,
                            "bytes": 1
                          }
                        ],
                        "totals": {
                          "requests": 1,
                          "rows": 1,
                          "bytes": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-ingest-stats",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-monitoring-health": {
      "post": {
        "operationId": "getMonitoringHealth",
        "summary": "Get monitoring health",
        "description": "Report whether Beaam's own collection is healthy — per integration, flagging any whose collector has errored or gone silent — plus the freshest check time.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean"
                        },
                        "lastActivityAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "issues": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "integrations": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "ok",
                        "lastActivityAt",
                        "issues",
                        "integrations"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "ok": false,
                        "lastActivityAt": "2026-01-01T00:00:00.000Z",
                        "issues": [
                          {}
                        ],
                        "integrations": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-monitoring-health",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-navigation-summary": {
      "post": {
        "operationId": "getNavigationSummary",
        "summary": "Get navigation summary",
        "description": "Return the active organization's broken and degraded watched-service counts for navigation attention state.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "broken": {
                          "type": "integer"
                        },
                        "degraded": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "broken",
                        "degraded"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "broken": 1,
                        "degraded": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-navigation-summary",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-now-overview": {
      "post": {
        "operationId": "getNowOverview",
        "summary": "Get the Now overview",
        "description": "Return the active organization's complete Now dashboard: service and incident state, collection health, activation, stacks, recent changes, and unfinished planned connections.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "board": {
                          "type": "object"
                        },
                        "activation": {
                          "type": "object"
                        },
                        "monitoring": {
                          "type": "object"
                        },
                        "stacks": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "activeOrganization": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "recentChanges": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "plannedConnections": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "board",
                        "activation",
                        "monitoring",
                        "stacks",
                        "activeOrganization",
                        "recentChanges",
                        "plannedConnections"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "board": {},
                        "activation": {},
                        "monitoring": {},
                        "stacks": [
                          {}
                        ],
                        "activeOrganization": {},
                        "recentChanges": [
                          {}
                        ],
                        "plannedConnections": {}
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-now-overview",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-public-status": {
      "post": {
        "operationId": "getPublicStatus",
        "summary": "Get a published status page",
        "description": "Return the deliberately limited service health and recent incidents for an explicitly published public status token.",
        "tags": [
          "status"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "Revocable public status identifier."
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": false
              },
              "example": {
                "token": "replace_with_token"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "not_found"
                          ]
                        },
                        "stack": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "environment": {
                              "type": "string"
                            },
                            "services": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            },
                            "incidents": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "stack": {
                          "name": "<name>",
                          "environment": "<environment>",
                          "services": [
                            {}
                          ],
                          "incidents": [
                            {}
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-public-status",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-service": {
      "post": {
        "operationId": "getService",
        "summary": "Get a service",
        "description": "Return one service's full detail — display name, type, external id, current health state, source, and sensible defaults.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service id to fetch."
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "service": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "display_name": {
                              "type": "string"
                            },
                            "custom_name": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "provider_name": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "type": {
                              "type": "string"
                            },
                            "external_id": {
                              "type": "string"
                            },
                            "current_state": {
                              "type": "string"
                            },
                            "source": {
                              "type": "string"
                            },
                            "is_watched": {
                              "type": "boolean"
                            },
                            "integration_id": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "last_reason": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "state_since": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "stack_id": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "muted_until": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "sensible_defaults": {
                              "type": "object"
                            },
                            "console_url": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "console_label": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "created_at": {
                              "type": "string",
                              "description": "When the service was discovered. Always present."
                            },
                            "watched_since": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "When the user asked for this to be watched. Null for anything unwatched, and for rows written before the column existed."
                            }
                          }
                        }
                      },
                      "required": [
                        "service"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "service": {
                          "id": "00000000-0000-4000-8000-000000000000",
                          "display_name": "<display_name>",
                          "custom_name": "<custom_name>",
                          "provider_name": "<provider_name>",
                          "type": "<type>",
                          "external_id": "<external_id>",
                          "current_state": "<current_state>",
                          "source": "<source>",
                          "is_watched": false,
                          "integration_id": "00000000-0000-4000-8000-000000000000",
                          "last_reason": "<last_reason>",
                          "state_since": "2026-01-01T00:00:00.000Z",
                          "stack_id": "00000000-0000-4000-8000-000000000000",
                          "muted_until": "2026-01-01T00:00:00.000Z",
                          "sensible_defaults": {},
                          "console_url": "https://example.com",
                          "console_label": "<console_label>",
                          "created_at": "2026-01-01T00:00:00.000Z",
                          "watched_since": "2026-01-01T00:00:00.000Z"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-service",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/get-service-detail": {
      "post": {
        "operationId": "getServiceDetail",
        "summary": "Get service detail payload",
        "description": "Return the active organization's bounded service workbench payload.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string"
                  },
                  "includeStacks": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "serviceId",
                  "includeStacks"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "includeStacks": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "description": "Everything the service screen shows, in one read. service and history are null when the service does not exist or is not visible to you.",
                      "properties": {
                        "service": {
                          "anyOf": [
                            {
                              "type": [
                                "object",
                                "null"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "display_name": {
                                  "type": "string"
                                },
                                "custom_name": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "provider_name": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "type": {
                                  "type": "string"
                                },
                                "external_id": {
                                  "type": "string"
                                },
                                "current_state": {
                                  "type": "string"
                                },
                                "source": {
                                  "type": "string"
                                },
                                "is_watched": {
                                  "type": "boolean"
                                },
                                "integration_id": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "last_reason": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "state_since": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "stack_id": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "muted_until": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "sensible_defaults": {
                                  "type": "object"
                                },
                                "console_url": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "console_label": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "created_at": {
                                  "type": "string",
                                  "description": "When the service was discovered. Always present."
                                },
                                "watched_since": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "When the user asked for this to be watched. Null for anything unwatched, and for rows written before the column existed."
                                }
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "history": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "summary": {
                                  "type": "object",
                                  "description": "Totals over the window: checks, quiet checks, uptime and p95 latency (null when nothing was measured).",
                                  "properties": {
                                    "totalChecks": {
                                      "type": "integer"
                                    },
                                    "quietChecks": {
                                      "type": "integer"
                                    },
                                    "uptimePercent": {
                                      "type": [
                                        "number",
                                        "null"
                                      ]
                                    },
                                    "p95LatencyMs": {
                                      "type": [
                                        "number",
                                        "null"
                                      ]
                                    },
                                    "hasHttp": {
                                      "type": "boolean"
                                    },
                                    "hasLatency": {
                                      "type": "boolean"
                                    },
                                    "hasError": {
                                      "type": "boolean"
                                    }
                                  },
                                  "required": [
                                    "totalChecks",
                                    "quietChecks",
                                    "uptimePercent",
                                    "p95LatencyMs",
                                    "hasHttp",
                                    "hasLatency",
                                    "hasError"
                                  ]
                                },
                                "latest": {
                                  "type": [
                                    "object",
                                    "null"
                                  ],
                                  "description": "The most recent check, or null when the service has none.",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "checked_at": {
                                      "type": "string"
                                    },
                                    "status": {
                                      "type": "string"
                                    },
                                    "latency_ms": {
                                      "type": [
                                        "number",
                                        "null"
                                      ]
                                    },
                                    "http_status": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "tool_call_success": {
                                      "type": [
                                        "boolean",
                                        "null"
                                      ]
                                    },
                                    "tool_call_error": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "metrics": {
                                      "type": [
                                        "object",
                                        "null"
                                      ],
                                      "additionalProperties": {
                                        "type": "number"
                                      }
                                    }
                                  }
                                },
                                "dailyUptime": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "day": {
                                        "type": "string"
                                      },
                                      "uptime": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "day",
                                      "uptime"
                                    ]
                                  }
                                },
                                "latencySeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "checkedAt": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "checkedAt",
                                      "value"
                                    ]
                                  }
                                },
                                "metricSeries": {
                                  "type": "object",
                                  "description": "One series per collected metric, keyed by metric name.",
                                  "additionalProperties": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "checkedAt": {
                                          "type": "string"
                                        },
                                        "value": {
                                          "type": "number"
                                        }
                                      },
                                      "required": [
                                        "checkedAt",
                                        "value"
                                      ]
                                    }
                                  }
                                },
                                "runs": {
                                  "type": "array",
                                  "description": "Consecutive checks with the same outcome, newest first.",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "status": {
                                        "type": "string"
                                      },
                                      "http_status": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ]
                                      },
                                      "latency_ms": {
                                        "type": [
                                          "number",
                                          "null"
                                        ]
                                      },
                                      "latencyMin": {
                                        "type": [
                                          "number",
                                          "null"
                                        ]
                                      },
                                      "latencyMax": {
                                        "type": [
                                          "number",
                                          "null"
                                        ]
                                      },
                                      "tool_call_error": {
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "latestAt": {
                                        "type": "string"
                                      },
                                      "oldestAt": {
                                        "type": "string"
                                      },
                                      "count": {
                                        "type": "integer"
                                      }
                                    }
                                  }
                                }
                              },
                              "required": [
                                "summary",
                                "latest",
                                "dailyUptime",
                                "latencySeries",
                                "metricSeries",
                                "runs"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recentChanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "summary": {
                                "type": "string"
                              },
                              "resource": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "occurred_at": {
                                "type": "string"
                              },
                              "integration_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "integration_label": {
                                "type": "string"
                              },
                              "integration_type": {
                                "type": "string"
                              },
                              "stack_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "stack_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        },
                        "channels": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "email",
                                  "sms",
                                  "push",
                                  "slack",
                                  "webhook"
                                ]
                              },
                              "label": {
                                "type": "string"
                              },
                              "destination": {
                                "type": "string"
                              },
                              "enabled": {
                                "type": "boolean"
                              },
                              "is_default": {
                                "type": "boolean"
                              },
                              "consent_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "When SMS consent was affirmed for this destination. Null for non-SMS channels or where no consent is on record."
                              },
                              "disabled_reason": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Why Beaam disabled this channel (e.g. the recipient replied STOP). Null if the user disabled it or it's enabled."
                              },
                              "lastTest": {
                                "type": "object",
                                "description": "The channel's latest test alert. status 'delivered' is proof it reaches you; 'accepted' is still waiting on the provider's receipt; anything else failed, with reason.",
                                "properties": {
                                  "status": {
                                    "type": "string"
                                  },
                                  "sentAt": {
                                    "type": "string"
                                  },
                                  "deliveredAt": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "reason": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                }
                              }
                            }
                          }
                        },
                        "serviceRouting": {
                          "type": "object",
                          "properties": {
                            "mode": {
                              "type": "string",
                              "enum": [
                                "global",
                                "custom"
                              ]
                            },
                            "channelIds": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "rules": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "stacks": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "environment": {
                                "type": "string"
                              },
                              "ingest_key_prefix": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "last_ingest_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Last successful OTLP ingest; null if this stack has never pushed telemetry."
                              },
                              "ingest_silent_since": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Set while telemetry has gone silent (no OTLP past the expected cadence)."
                              },
                              "public_status_enabled": {
                                "type": "boolean"
                              },
                              "public_status_slug": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "public_status_show_service_names": {
                                "type": "boolean"
                              },
                              "public_status_show_incidents": {
                                "type": "boolean"
                              },
                              "service_count": {
                                "type": "number"
                              },
                              "otel_registration": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "registered",
                                  "pending",
                                  "blocked_by_plan",
                                  null
                                ],
                                "description": "For a stack that has received OpenTelemetry: whether its services are being registered, or held back because the organization is at its plan's integration limit."
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "service",
                        "history",
                        "recentChanges",
                        "channels",
                        "serviceRouting",
                        "rules",
                        "stacks"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "service": {
                          "id": "00000000-0000-4000-8000-000000000000",
                          "display_name": "<display_name>",
                          "custom_name": "<custom_name>",
                          "provider_name": "<provider_name>",
                          "type": "<type>",
                          "external_id": "<external_id>",
                          "current_state": "<current_state>",
                          "source": "<source>",
                          "is_watched": false,
                          "integration_id": "00000000-0000-4000-8000-000000000000",
                          "last_reason": "<last_reason>",
                          "state_since": "2026-01-01T00:00:00.000Z",
                          "stack_id": "00000000-0000-4000-8000-000000000000",
                          "muted_until": "2026-01-01T00:00:00.000Z",
                          "sensible_defaults": {},
                          "console_url": "https://example.com",
                          "console_label": "<console_label>",
                          "created_at": "2026-01-01T00:00:00.000Z",
                          "watched_since": "2026-01-01T00:00:00.000Z"
                        },
                        "history": {
                          "summary": {
                            "totalChecks": 1,
                            "quietChecks": 1,
                            "uptimePercent": 1,
                            "p95LatencyMs": 1,
                            "hasHttp": false,
                            "hasLatency": false,
                            "hasError": false
                          },
                          "latest": {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "checked_at": "2026-01-01T00:00:00.000Z",
                            "status": "<status>",
                            "latency_ms": 1,
                            "http_status": 1,
                            "tool_call_success": false,
                            "tool_call_error": "<tool_call_error>",
                            "metrics": {
                              "key": 1
                            }
                          },
                          "dailyUptime": [
                            {
                              "day": "<day>",
                              "uptime": 1
                            }
                          ],
                          "latencySeries": [
                            {
                              "checkedAt": "2026-01-01T00:00:00.000Z",
                              "value": 1
                            }
                          ],
                          "metricSeries": {
                            "key": [
                              {
                                "checkedAt": "2026-01-01T00:00:00.000Z",
                                "value": 1
                              }
                            ]
                          },
                          "runs": [
                            {
                              "id": "00000000-0000-4000-8000-000000000000",
                              "status": "<status>",
                              "http_status": 1,
                              "latency_ms": 1,
                              "latencyMin": 1,
                              "latencyMax": 1,
                              "tool_call_error": "<tool_call_error>",
                              "latestAt": "2026-01-01T00:00:00.000Z",
                              "oldestAt": "2026-01-01T00:00:00.000Z",
                              "count": 25
                            }
                          ]
                        },
                        "recentChanges": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "kind": "<kind>",
                            "summary": "<summary>",
                            "resource": "<resource>",
                            "occurred_at": "2026-01-01T00:00:00.000Z",
                            "integration_id": "00000000-0000-4000-8000-000000000000",
                            "integration_label": "<integration_label>",
                            "integration_type": "<integration_type>",
                            "stack_id": "00000000-0000-4000-8000-000000000000",
                            "stack_name": "<stack_name>"
                          }
                        ],
                        "channels": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "type": "email",
                            "label": "<label>",
                            "destination": "<destination>",
                            "enabled": false,
                            "is_default": false,
                            "consent_at": "2026-01-01T00:00:00.000Z",
                            "disabled_reason": "<disabled_reason>",
                            "lastTest": {
                              "status": "<status>",
                              "sentAt": "2026-01-01T00:00:00.000Z",
                              "deliveredAt": "2026-01-01T00:00:00.000Z",
                              "reason": "<reason>"
                            }
                          }
                        ],
                        "serviceRouting": {
                          "mode": "global",
                          "channelIds": [
                            "00000000-0000-4000-8000-000000000000"
                          ]
                        },
                        "rules": [
                          {}
                        ],
                        "stacks": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "name": "<name>",
                            "slug": "<slug>",
                            "environment": "<environment>",
                            "ingest_key_prefix": "<ingest_key_prefix>",
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "last_ingest_at": "2026-01-01T00:00:00.000Z",
                            "ingest_silent_since": "2026-01-01T00:00:00.000Z",
                            "public_status_enabled": false,
                            "public_status_slug": "<public_status_slug>",
                            "public_status_show_service_names": false,
                            "public_status_show_incidents": false,
                            "service_count": 25,
                            "otel_registration": "registered"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-service-detail",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/get-status-board": {
      "post": {
        "operationId": "getStatusBoard",
        "summary": "Get the status board",
        "description": "Return everything the status board shows in one call: watched services, connections, open incidents, recent alerts, and when Beaam last checked.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "connections": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "incidents": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "alerts": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "lastChecked": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "services",
                        "connections",
                        "incidents",
                        "alerts",
                        "lastChecked"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "services": [
                          {}
                        ],
                        "connections": [
                          {}
                        ],
                        "incidents": [
                          {}
                        ],
                        "alerts": [
                          {}
                        ],
                        "lastChecked": "<lastChecked>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "get-status-board",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-assistant-connections": {
      "post": {
        "operationId": "listAssistantConnections",
        "summary": "List connected AI assistants",
        "description": "Return the AI clients connected to this Beaam account over MCP — each one's name, when it was authorized, when it last called a tool, and whether it has asked anything yet. No token or secret material is returned.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "connections": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "clientId": {
                                "type": "string"
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "connectedAt": {
                                "type": "string"
                              },
                              "lastUsedAt": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "active",
                                  "pending",
                                  "idle"
                                ]
                              }
                            },
                            "required": [
                              "clientId",
                              "connectedAt",
                              "state"
                            ]
                          }
                        },
                        "settlingWindowMinutes": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "connections",
                        "settlingWindowMinutes"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "connections": [
                          {
                            "clientId": "00000000-0000-4000-8000-000000000000",
                            "name": "<name>",
                            "connectedAt": "2026-01-01T00:00:00.000Z",
                            "lastUsedAt": "2026-01-01T00:00:00.000Z",
                            "state": "active"
                          }
                        ],
                        "settlingWindowMinutes": 25
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-assistant-connections",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-detection-rules": {
      "post": {
        "operationId": "listDetectionRules",
        "summary": "List a service's alert rules",
        "description": "Return the alert rules Beaam uses to decide whether to alert for a service — the sensible defaults plus any overrides — with each rule's threshold, severity, and hysteresis.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string"
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "serviceType": {
                          "type": "string"
                        },
                        "rules": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "serviceType",
                        "rules"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "serviceType": "<serviceType>",
                        "rules": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-detection-rules",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-integration-rules": {
      "post": {
        "operationId": "listIntegrationRules",
        "summary": "List provider-level alert rules",
        "description": "Return the default alert rules for a provider or service type (applied to all its services), with each rule's threshold, severity, and whether it's been customised.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "description": "Return rules for every monitorable service type of this provider (e.g. cloudflare)."
                  },
                  "serviceType": {
                    "type": "string",
                    "description": "Return rules for just this service type (e.g. mongodb.cluster)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "provider": "cloudflare",
                "serviceType": "replace_with_service_type"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "rules": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "chartedOnly": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "rules",
                        "chartedOnly"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "rules": [
                          {}
                        ],
                        "chartedOnly": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-integration-rules",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-service-edges": {
      "post": {
        "operationId": "listServiceEdges",
        "summary": "List what Beaam has learned about a service",
        "description": "Show the correlation Beaam has learned for one service from your own history — which services it tends to go bad before, and which tend to go bad before it — with any verdict you have given.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service to describe."
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "edges": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "edges"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "edges": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-service-edges",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/list-services": {
      "post": {
        "operationId": "listServices",
        "summary": "List services",
        "description": "Return the services Beaam has discovered for the signed-in user, with each one's current health state and whether it's being watched. Pass watchedOnly to limit to watched services.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "watchedOnly": {
                    "type": "boolean",
                    "description": "Only return services Beaam is actively watching."
                  },
                  "stackId": {
                    "type": "string",
                    "description": "Only return services in this stack."
                  },
                  "integrationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only return services belonging to these integrations."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "watchedOnly": false,
                "stackId": "00000000-0000-4000-8000-000000000000",
                "integrationIds": [
                  "00000000-0000-4000-8000-000000000000"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "display_name": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "external_id": {
                                "type": "string"
                              },
                              "current_state": {
                                "type": "string"
                              },
                              "is_watched": {
                                "type": "boolean"
                              },
                              "muted_until": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "integration_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "stack_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "missing_since": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Set when re-discovery can no longer find the resource. Null = still present."
                              },
                              "last_reason": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Why the service is in current_state, in a sentence — e.g. \"This cluster is paused in Atlas\". Null means not recorded, never \"no reason\"."
                              },
                              "state_since": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "When current_state began — the \"for 9 days\" half of a useful sentence. Written only on a state CHANGE, so it is null for a newly discovered service. Null means not recorded."
                              },
                              "created_at": {
                                "type": "string",
                                "description": "When the service was discovered. Always present."
                              },
                              "watched_since": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "When the user asked for this to be watched. Null for anything unwatched, and for rows written before the column existed."
                              },
                              "console_url": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Where this resource lives in the provider's own console, or null when the provider has no addressable page for it."
                              },
                              "console_label": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "What to call that console — the provider's own name, e.g. \"Cloudflare\"."
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "services"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "services": [
                          {
                            "id": "00000000-0000-4000-8000-000000000000",
                            "display_name": "<display_name>",
                            "type": "<type>",
                            "external_id": "<external_id>",
                            "current_state": "<current_state>",
                            "is_watched": false,
                            "muted_until": "2026-01-01T00:00:00.000Z",
                            "integration_id": "00000000-0000-4000-8000-000000000000",
                            "stack_id": "00000000-0000-4000-8000-000000000000",
                            "missing_since": "2026-01-01T00:00:00.000Z",
                            "last_reason": "<last_reason>",
                            "state_since": "2026-01-01T00:00:00.000Z",
                            "created_at": "2026-01-01T00:00:00.000Z",
                            "watched_since": "2026-01-01T00:00:00.000Z",
                            "console_url": "https://example.com",
                            "console_label": "<console_label>"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "list-services",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/query-metrics": {
      "post": {
        "operationId": "queryMetrics",
        "summary": "Query metrics",
        "description": "Return recent OTel metrics for a stack from the telemetry store, optionally filtered to one metric.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string",
                    "description": "Stack to query; defaults to your first stack."
                  },
                  "metricName": {
                    "type": "string",
                    "description": "Filter to one metric."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Max rows (default 100)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000",
                "metricName": "replace_with_metric_name",
                "limit": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "metrics": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "metrics"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "metrics": [
                          {}
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "query-metrics",
        "x-beaam-read-only": true,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/rename-service": {
      "post": {
        "operationId": "renameService",
        "summary": "Rename a service",
        "description": "Give a watched service a name of your own, or send an empty name to restore the provider's. The provider's name is remembered underneath, so re-discovery will not overwrite yours.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service to rename."
                  },
                  "name": {
                    "type": "string",
                    "description": "What to call it. Send an empty string to restore the provider's own name.",
                    "maxLength": 120
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "name": "replace_with_name"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "displayName": {
                          "type": "string"
                        },
                        "custom": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "serviceId": "00000000-0000-4000-8000-000000000000",
                        "displayName": "<displayName>",
                        "custom": false,
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "rename-service",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/review-correlation-edge": {
      "post": {
        "operationId": "reviewCorrelationEdge",
        "summary": "Confirm or reject a learned correlation",
        "description": "Tell Beaam whether a correlation it learned from your history is a real dependency or a coincidence. A confirmed pair is trusted below the usual thresholds; a rejected one is never used again.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fromService": {
                    "type": "string",
                    "description": "The service that goes bad first in the pair."
                  },
                  "toService": {
                    "type": "string",
                    "description": "The service that follows it."
                  },
                  "verdict": {
                    "type": "string",
                    "enum": [
                      "confirmed",
                      "rejected",
                      "clear"
                    ],
                    "description": "confirmed: this is a real dependency, trust it below the usual thresholds. rejected: this is coincidence, never use it. clear: remove your verdict and judge it on the numbers again."
                  },
                  "note": {
                    "type": "string",
                    "description": "Optional: why, for whoever looks next."
                  }
                },
                "required": [
                  "fromService",
                  "toService",
                  "verdict"
                ],
                "additionalProperties": false
              },
              "example": {
                "fromService": "replace_with_from_service",
                "toService": "replace_with_to_service",
                "verdict": "confirmed",
                "note": "replace_with_note"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "fromService": {
                          "type": "string"
                        },
                        "toService": {
                          "type": "string"
                        },
                        "verdict": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "effect": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "fromService",
                        "toService",
                        "verdict",
                        "effect"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "fromService": "<fromService>",
                        "toService": "<toService>",
                        "verdict": "<verdict>",
                        "effect": "<effect>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "review-correlation-edge",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-detection-rule": {
      "post": {
        "operationId": "setDetectionRule",
        "summary": "Set a service's alert rule",
        "description": "Change a service's alert rule: set its threshold, its level (degraded/broken), enable/disable it, or reset it to the default. Pass serviceId and metric.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string"
                  },
                  "metric": {
                    "type": "string",
                    "description": "The rule's metric, e.g. sentry.errors_per_5m."
                  },
                  "threshold": {
                    "type": "number",
                    "description": "New threshold (numeric rules only)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Turn this rule on or off for the service."
                  },
                  "severity": {
                    "type": "string",
                    "enum": [
                      "degraded",
                      "broken"
                    ],
                    "description": "Level raised when it fires: degraded (warm) or broken."
                  },
                  "reset": {
                    "type": "boolean",
                    "description": "Remove the override and restore the default."
                  }
                },
                "required": [
                  "serviceId",
                  "metric"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "metric": "replace_with_metric",
                "threshold": 1,
                "enabled": false,
                "severity": "degraded",
                "reset": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-detection-rule",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-integration-rule": {
      "post": {
        "operationId": "setIntegrationRule",
        "summary": "Set a provider-level alert rule",
        "description": "Change the default alert rule for a service type (applies to all its services): set threshold, its level (degraded/broken), enable/disable, or reset. Individual services can still override.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceType": {
                    "type": "string",
                    "description": "The service type these defaults apply to, e.g. mongodb.cluster."
                  },
                  "metric": {
                    "type": "string",
                    "description": "The rule's metric, e.g. mongodb.disk_used_percent."
                  },
                  "threshold": {
                    "type": "number",
                    "description": "New default threshold (numeric rules only)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Turn this rule on or off for all services of the type."
                  },
                  "severity": {
                    "type": "string",
                    "enum": [
                      "degraded",
                      "broken"
                    ],
                    "description": "Level raised when it fires: degraded (warm) or broken."
                  },
                  "reset": {
                    "type": "boolean",
                    "description": "Remove the provider-level override (back to Beaam's default)."
                  }
                },
                "required": [
                  "serviceType",
                  "metric"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceType": "replace_with_service_type",
                "metric": "replace_with_metric",
                "threshold": 1,
                "enabled": false,
                "severity": "degraded",
                "reset": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-integration-rule",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-public-status": {
      "post": {
        "operationId": "setPublicStatus",
        "summary": "Configure public status publishing",
        "description": "Publish or unpublish a stack status page, choose its limited contents, or rotate its revocable public identifier.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stackId": {
                    "type": "string"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "showServiceNames": {
                    "type": "boolean"
                  },
                  "showIncidents": {
                    "type": "boolean"
                  },
                  "rotateToken": {
                    "type": "boolean",
                    "description": "Issue a new public identifier and revoke the old URL."
                  }
                },
                "required": [
                  "stackId",
                  "enabled"
                ],
                "additionalProperties": false
              },
              "example": {
                "stackId": "00000000-0000-4000-8000-000000000000",
                "enabled": false,
                "showServiceNames": false,
                "showIncidents": false,
                "rotateToken": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "publicToken": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "message": "<message>",
                        "publicToken": "<token>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-public-status",
        "x-beaam-read-only": false,
        "x-beaam-destructive": false,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": false
      }
    },
    "/api/v1/set-service-mute": {
      "post": {
        "operationId": "setServiceMute",
        "summary": "Mute a service",
        "description": "Stop sending alerts for one service for a bounded time (max 24h), while it keeps being checked and incidents keep opening. Pass minutes: 0 to unmute.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service to mute."
                  },
                  "minutes": {
                    "type": "integer",
                    "description": "How long to stay quiet, up to 1440 (24h). 0 unmutes."
                  }
                },
                "required": [
                  "serviceId",
                  "minutes"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "minutes": 25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "mutedUntil": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "mutedUntil": "<mutedUntil>",
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-service-mute",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    },
    "/api/v1/set-service-watched": {
      "post": {
        "operationId": "setServiceWatched",
        "summary": "Watch or unwatch one service",
        "description": "Start or stop watching a single service. Stopping ends collection for it — use set-service-mute instead to keep the record while silencing alerts.\n\n**Can refuse in-band.** A refusal (a plan limit, a credential the provider rejected) is `200` with `data.status: \"error\"` and a `data.message` written to be shown to a person. Check `data.status`, not just the HTTP status.\n\n**Destructive.** Changes or removes something that already exists.",
        "tags": [
          "status"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "The service to change."
                  },
                  "watched": {
                    "type": "boolean",
                    "description": "true to watch it, false to stop collecting entirely."
                  }
                },
                "required": [
                  "serviceId",
                  "watched"
                ],
                "additionalProperties": false
              },
              "example": {
                "serviceId": "00000000-0000-4000-8000-000000000000",
                "watched": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted. `data.status` says whether the operation was carried out or refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "watched": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status"
                      ]
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Carried out",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "ok",
                        "watched": false,
                        "message": "<message>"
                      }
                    }
                  },
                  "refused": {
                    "summary": "Refused in-band (still 200)",
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "error",
                        "message": "<why it was refused, written to show a person — e.g. a plan limit, or a credential the provider rejected>"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          }
        },
        "x-beaam-capability": "set-service-watched",
        "x-beaam-read-only": false,
        "x-beaam-destructive": true,
        "x-beaam-open-world": false,
        "x-beaam-mcp-exposed": true
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → API keys in the app, sent as `Authorization: Bearer <key>`."
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string",
            "description": "The message, ready to show a person. Always a string."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The body was not valid JSON, or did not match the operation's input schema.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "No credential, or one that is invalid or revoked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "TooLarge": {
        "description": "The request body is larger than the API accepts.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. Wait for `retry-after` seconds.",
        "headers": {
          "retry-after": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Failed": {
        "description": "The capability itself failed. The message says why.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    }
  }
}