{
 "openapi": "3.0.3",
 "info": {
  "title": "Bramble Partner portal API",
  "version": "2026-11-13",
  "description": "The Partner portal for MSPs: your customers with health summaries, partnership requests and recent activity. Customers approve partnerships in their own Admin Centre (see [Partners](/apps/admin/api/partners)).\n"
 },
 "servers": [
  {
   "url": "https://{org}.brambleit.cloud/api",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  },
  {
   "url": "https://{org}.brambleit.cloud/partner",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "session": {
    "type": "apiKey",
    "in": "cookie",
    "name": "sso_session"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
   }
  }
 },
 "tags": [
  {
   "name": "Customers",
   "description": "The organisations you manage, their health, and recent activity across them."
  },
  {
   "name": "Requests",
   "description": "Asking an organisation to let you manage it, and withdrawing a request."
  }
 ],
 "paths": {
  "/v1/partner/me": {
   "get": {
    "tags": [
     "Customers"
    ],
    "summary": "Your partner access",
    "operationId": "get-v1-partner-me",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "can_use": {
           "type": "boolean"
          },
          "customers": {
           "type": "number"
          },
          "pending": {
           "type": "number"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  },
  "/v1/partner/customers": {
   "get": {
    "tags": [
     "Customers"
    ],
    "summary": "Your customers with health summaries",
    "operationId": "get-v1-partner-customers",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "customers": {
           "type": "array",
           "items": {}
          },
          "requests": {
           "type": "array",
           "items": {}
          },
          "permissions": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  },
  "/v1/partner/requests": {
   "post": {
    "tags": [
     "Requests"
    ],
    "summary": "Ask to manage an organisation",
    "operationId": "post-v1-partner-requests",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          },
          "customer": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "That's your own organisation."
     },
     "404": {
      "description": "No Bramble organisation uses that domain."
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "domain": {
          "type": "string",
          "description": "One of the organisation's verified domains."
         },
         "permissions": {
          "type": "array",
          "items": {},
          "description": "What you're asking for: `devices.read`, `device_management.manage`."
         },
         "note": {
          "type": "string",
          "description": "A message for them."
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/partner/requests/{id}/withdraw": {
   "post": {
    "tags": [
     "Requests"
    ],
    "summary": "Withdraw a request",
    "operationId": "post-v1-partner-requests-id-withdraw",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     },
     "409": {
      "description": "This has already ended."
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  },
  "/v1/partner/activity": {
   "get": {
    "tags": [
     "Customers"
    ],
    "summary": "Recent activity across your customers",
    "operationId": "get-v1-partner-activity",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "activity": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "created_at": {
              "type": "string",
              "format": "date-time"
             },
             "user_email": {
              "type": "string",
              "nullable": true
             },
             "method": {
              "type": "string"
             },
             "path": {
              "type": "string"
             },
             "status_code": {
              "type": "integer"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  }
 }
}