{
 "openapi": "3.1.0",
 "info": {
  "title": "paas.build API",
  "version": "0.2.0",
  "description": "Payments for AI builders on UniPaaS rails (UNIPaaS Financial Services Ltd, FCA-authorised Payment Institution No. 929994). Identify a business, take it live with a real merchant account (progressive KYB - individuals in the UK, EU and US go live the same day), and create payable checkouts. No API key is needed for these three endpoints; secrets stay server-side. Also available as MCP: streamable HTTP at https://paas.build/mcp, legacy SSE at https://paas.build/sse, or `npx -y @paasbuild/mcp`.",
  "contact": {
   "name": "Oded Kovach, co-founder",
   "url": "https://paas.build/contact",
   "email": "oded@unipaas.com"
  },
  "termsOfService": "https://paas.build/terms"
 },
 "servers": [
  {
   "url": "https://paas.build"
  }
 ],
 "paths": {
  "/api/identify": {
   "post": {
    "operationId": "identifyBusiness",
    "summary": "Identify a business from a name, website or free-text phrase",
    "description": "Uses Claude with live web search to resolve a business: display name, what it does, website, country, region (uk/eu/us/other). Call this first when you only have a phrase like 'a pottery studio in London'.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "input"
        ],
        "properties": {
         "input": {
          "type": "string",
          "description": "Business name, website domain, or free-text description",
          "examples": [
           "we're a pilates studio in London - darcie@studio.co",
           "triibe.ai"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Resolved business fields",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "data": {
           "type": "object",
           "properties": {
            "business": {
             "type": "string"
            },
            "what": {
             "type": "string"
            },
            "company_no": {
             "type": [
              "string",
              "null"
             ]
            },
            "email": {
             "type": [
              "string",
              "null"
             ]
            },
            "website": {
             "type": [
              "string",
              "null"
             ]
            },
            "country": {
             "type": [
              "string",
              "null"
             ]
            },
            "region": {
             "type": "string",
             "enum": [
              "uk",
              "eu",
              "us",
              "other",
              "unknown"
             ]
            },
            "confidence": {
             "type": "string",
             "enum": [
              "high",
              "low"
             ]
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/go-live": {
   "post": {
    "operationId": "goLive",
    "summary": "Create a real merchant account (sandbox + production) and return access tokens",
    "description": "Progressive KYB on FCA-authorised rails. Individuals go live instantly with a capped account; companies also receive an onboarding link for identity/document steps. Returns a vendorId and a narrow, checkout-only access token per environment. Pass notify=true to also email the keys to the builder and record the lead.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "business"
        ],
        "properties": {
         "business": {
          "type": "string",
          "description": "Business / trading name"
         },
         "website": {
          "type": "string"
         },
         "email": {
          "type": "string",
          "description": "Contact email - receives the keys when notify=true"
         },
         "company_no": {
          "type": "string",
          "description": "Company registration number; presence = company vendor, absence = individual"
         },
         "region": {
          "type": "string",
          "enum": [
           "uk",
           "eu",
           "us"
          ]
         },
         "country": {
          "type": "string",
          "description": "Country name or ISO-2 code (overrides region)"
         },
         "env": {
          "type": "string",
          "enum": [
           "sandbox",
           "production",
           "both"
          ],
          "default": "both"
         },
         "notify": {
          "type": "boolean",
          "description": "Email the keys to `email` and record the lead"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Vendor(s) created with tokens",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "business": {
           "type": "string"
          },
          "vendorId": {
           "type": "string",
           "description": "Convenience: the sandbox vendorId"
          },
          "onboardingLink": {
           "type": [
            "string",
            "null"
           ]
          },
          "sandbox": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "vendorId": {
             "type": "string"
            },
            "accessToken": {
             "type": "string"
            },
            "onboardingLink": {
             "type": [
              "string",
              "null"
             ]
            }
           }
          },
          "production": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "vendorId": {
             "type": "string"
            },
            "accessToken": {
             "type": "string"
            },
            "onboardingLink": {
             "type": [
              "string",
              "null"
             ]
            }
           }
          },
          "emailed": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/checkout": {
   "post": {
    "operationId": "createCheckout",
    "summary": "Create a hosted checkout for a live vendor and return a payable shortLink",
    "description": "The vendor must already exist (goLive). In sandbox, pay the link with test card 4761 3441 3614 1390, any future date, any CVC.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "vendorId",
         "amount"
        ],
        "properties": {
         "vendorId": {
          "type": "string"
         },
         "amount": {
          "type": "number",
          "description": "Major units, e.g. 12 = \u00a312.00"
         },
         "currency": {
          "type": "string",
          "default": "GBP"
         },
         "reference": {
          "type": "string",
          "description": "Your order/invoice reference"
         },
         "env": {
          "type": "string",
          "enum": [
           "sandbox",
           "production"
          ],
          "default": "sandbox"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Checkout created",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "shortLink": {
           "type": "string",
           "description": "Payable hosted checkout URL"
          },
          "sessionToken": {
           "type": "string",
           "description": "For embedding with the UniPaaS buyerComponents SDK"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/whoami": {
   "get": {
    "operationId": "whoami",
    "summary": "Read-only credential check (no side effects)",
    "description": "Verifies a paas.build access token locally and returns its scope. The safe first call for agents. Auth failures return real HTTP 401 with {ok:false, error:{code, message}}.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Token valid",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "vendorId": {
           "type": [
            "string",
            "null"
           ]
          },
          "merchantName": {
           "type": [
            "string",
            "null"
           ]
          },
          "env": {
           "type": [
            "string",
            "null"
           ]
          },
          "scopes": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Invalid or missing token",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "error": {
           "type": "object",
           "properties": {
            "code": {
             "type": "string"
            },
            "message": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 },
 "externalDocs": {
  "description": "Agent-first docs, MCP install and recipes",
  "url": "https://paas.build/agents"
 },
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
   }
  }
 }
}