BusinessMCP Signup API

openapi: 3.2.0
info:
  title: BusinessMCP Signup API
  version: 3.0.0
  description: 'The BI REST API: read your contacts, accounts and analytics sessions, send server-side events, export CSV, and drive the AI business analyst. Authenticate with a workspace key as `Authorization: Bearer mcph_...` (create one in Settings → API & access, or through the headless signup). Every key runs under its access policy; fields outside its data classes come back redacted. The same data and the full tool set are on the MCP endpoint.'
  contact:
    url: https://businessmcp.com/contact
servers:
- url: https://businessmcp.com/api/v1
security:
- bearer: []
tags:
- name: Signup
  description: Headless signup for AI agents.
paths:
  /signup/start:
    post:
      operationId: signupStart
      summary: 'Headless signup, step 1: email the person a code'
      description: 'Unauthenticated by design: how an AI agent signs a person up. The answer is the same whether or not the address already has an account. Rate limits: 5 per IP per hour and 3 per address per day.'
      tags:
      - Signup
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                website:
                  type: string
                  description: A domain, e.g. acme.com.
              required:
              - email
      responses:
        '200':
          description: Code sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    const: true
                  signup_id:
                    type: string
                  expires_in:
                    type: integer
        '400':
          description: invalid_json, invalid_email, disposable_email or invalid_input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '502':
          description: The email could not be sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /signup/verify:
    post:
      operationId: signupVerify
      summary: 'Headless signup, step 2: redeem the code for an mcph_ key'
      description: 'Unauthenticated by design: the emailed code is the proof. Returns a full-access workspace key, shown once. Rate limits: 30 per IP per hour and 10 attempts per address per hour.'
      tags:
      - Signup
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signup_id:
                  type: string
                code:
                  type: string
              required:
              - signup_id
              - code
      responses:
        '200':
          description: Signed up.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    const: true
                  api_key:
                    type: string
                  workspace_id:
                    type: string
                  mcp_url:
                    type: string
                  dashboard_url:
                    type: string
                  install_snippet:
                    type: string
                  next_steps:
                    type: array
                    items:
                      type: string
        '400':
          description: invalid_json or invalid_signup_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          description: Wrong or expired code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '403':
          description: The workspace enforces two-factor sign-in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '409':
          description: The workspace could not be created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
components:
  schemas:
    SimpleError:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
        detail:
          type: string
      required:
      - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A BusinessMCP workspace key (mcph_…).
externalDocs:
  description: API reference
  url: https://businessmcp.com/docs/api