{
  "openapi": "3.1.0",
  "info": {
    "title": "BookedUp public API",
    "version": "2026-11-11",
    "summary": "OAuth + MCP for AI assistants, and API-key endpoints for leads and webhooks.",
    "description": "Everything is scoped to one business. AI assistants should use the MCP server (see /developers/mcp); the REST endpoints below are for integrations like Zapier. Webhook payloads are documented at https://getbookedup.ai/developers#events."
  },
  "servers": [
    {
      "url": "https://getbookedup.ai"
    }
  ],
  "externalDocs": {
    "url": "https://getbookedup.ai/developers",
    "description": "Developer docs"
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A bk_live_… API key from Settings > Integrations > API keys."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "oauth": {
        "type": "oauth2",
        "description": "Authorization code + PKCE (S256). Dynamic Client Registration and Client ID Metadata Documents are supported. Tokens are bound to the resource https://getbookedup.ai/mcp.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://getbookedup.ai/oauth/authorize",
            "tokenUrl": "https://getbookedup.ai/api/oauth/token",
            "refreshUrl": "https://getbookedup.ai/api/oauth/token",
            "scopes": {
              "settings:read": "See your business info, hours, closures, appointment types, FAQ cards and settings",
              "hours:write": "Change your business hours and holiday closures (you can undo any change)",
              "services:write": "Edit your services, service area and appointment types (you can undo any change)",
              "knowledge:write": "Add and edit FAQ cards (you can undo any change). New AI instructions wait for your approval",
              "intake:write": "Change what the receptionist asks callers and how calls are tagged (you can undo any change)",
              "calls:write": "Mark calls as spam and block or allow phone numbers (you can undo any change)",
              "greeting:write": "Propose greeting, voice, language and goodbye-message changes (you approve each one before callers hear it)",
              "transfers:write": "Propose changes to who gets live transfers (you approve each one before calls ring anyone)",
              "calls:read": "Read call summaries and booked appointments (phone numbers masked)",
              "calls:transcripts": "Read full call transcripts. These contain what your callers said.",
              "calls:recordings": "Listen to call recordings (links expire after 10 minutes)"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "OAuthError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "error_description": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Lead": {
        "type": "object",
        "description": "Same shape as the data of lead.* webhook events. From POST /leads, service_needed comes back as issue and notes as summary.",
        "additionalProperties": true,
        "properties": {
          "lead_id": {
            "type": "string",
            "format": "uuid"
          },
          "source": {
            "type": "string",
            "enum": [
              "phone",
              "booking_page",
              "manual"
            ],
            "description": "manual = added by hand: in the dashboard or with POST /leads"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "missed",
              "voicemail",
              "in-progress",
              "blocked",
              "manual"
            ],
            "description": "manual = a hand-added lead (no call)"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "booked",
              "urgent",
              "callback_requested",
              "not_qualified",
              "spam",
              "lead"
            ],
            "description": "lead = no specific outcome yet (e.g. a hand-added lead)"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer"
            ]
          },
          "method": {
            "type": "string",
            "examples": [
              "initialize",
              "tools/list",
              "tools/call"
            ]
          },
          "params": {
            "type": "object"
          }
        }
      }
    }
  },
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "MCP endpoint (Streamable HTTP, stateless)",
        "description": "One JSON-RPC message per request: initialize, ping, tools/list, tools/call. Tool reference: https://getbookedup.ai/developers/mcp. 401 responses carry WWW-Authenticate with resource_metadata; 403 insufficient_scope names the scope to request.",
        "security": [
          {
            "oauth": []
          }
        ],
        "parameters": [
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "2026-07-28",
                "2025-11-25",
                "2025-06-18",
                "2025-03-26"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          },
          "202": {
            "description": "Notification accepted"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "insufficient_scope"
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": {
        "operationId": "protectedResourceMetadata",
        "summary": "RFC 9728 metadata for the MCP endpoint",
        "responses": {
          "200": {
            "description": "Metadata"
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "authorizationServerMetadata",
        "summary": "RFC 8414 metadata",
        "responses": {
          "200": {
            "description": "Metadata"
          }
        }
      }
    },
    "/api/oauth/register": {
      "post": {
        "operationId": "registerClient",
        "summary": "Dynamic Client Registration (RFC 7591)",
        "description": "redirect_uris must be https, or http on 127.0.0.1/localhost (any port). token_endpoint_auth_method: none (default), client_secret_post or client_secret_basic. 20 per hour per IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "redirect_uris"
                ],
                "properties": {
                  "client_name": {
                    "type": "string"
                  },
                  "redirect_uris": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "maxItems": 10
                  },
                  "token_endpoint_auth_method": {
                    "type": "string",
                    "enum": [
                      "none",
                      "client_secret_post",
                      "client_secret_basic"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered client"
          },
          "400": {
            "description": "invalid_redirect_uri or invalid_client_metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/token": {
      "post": {
        "operationId": "token",
        "summary": "Token endpoint",
        "description": "grant_type=authorization_code (code, redirect_uri, code_verifier, client_id, resource) or refresh_token (refresh_token, client_id, optional narrower scope). Refresh tokens rotate; reusing one ends the connection.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code",
                      "refresh_token"
                    ]
                  },
                  "code": {
                    "type": "string"
                  },
                  "redirect_uri": {
                    "type": "string"
                  },
                  "code_verifier": {
                    "type": "string"
                  },
                  "refresh_token": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "scope": {
                    "type": "string"
                  },
                  "resource": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "access_token (1 hour), refresh_token, scope"
          },
          "400": {
            "description": "invalid_grant, invalid_scope, invalid_target, unsupported_grant_type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          },
          "401": {
            "description": "invalid_client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/revoke": {
      "post": {
        "operationId": "revoke",
        "summary": "Token revocation (RFC 7009)",
        "description": "Revoking a refresh token ends the whole connection.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked (or unknown token)"
          }
        }
      }
    },
    "/api/integrations/zapier/me": {
      "get": {
        "operationId": "checkApiKey",
        "summary": "Check an API key",
        "security": [
          {
            "apiKey": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "{ business: { id, name } }",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key (send Authorization: Bearer <key> or X-API-Key) or invalid / revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: 120 per minute per key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/zapier/subscribe": {
      "post": {
        "operationId": "subscribe",
        "summary": "Subscribe an HTTPS URL to one event (max 50)",
        "security": [
          {
            "apiKey": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target_url",
                  "event"
                ],
                "properties": {
                  "target_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "lead.created",
                      "lead.updated",
                      "call.completed",
                      "booking.created",
                      "booking.rescheduled",
                      "booking.cancelled"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "{ id, event, target_url }",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input, or \"Invalid JSON body\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key (send Authorization: Bearer <key> or X-API-Key) or invalid / revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request too large (the limit is 32 KB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: 120 per minute per key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/zapier/unsubscribe": {
      "delete": {
        "operationId": "unsubscribe",
        "summary": "Remove a subscription (idempotent)",
        "security": [
          {
            "apiKey": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ ok: true }",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "id is required, or \"Invalid JSON body\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key (send Authorization: Bearer <key> or X-API-Key) or invalid / revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request too large (the limit is 32 KB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: 120 per minute per key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/zapier/samples/{event}": {
      "get": {
        "operationId": "samples",
        "summary": "Up to 3 recent payloads of an event (or a sample)",
        "security": [
          {
            "apiKey": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "event",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "lead.created",
                "lead.updated",
                "call.completed",
                "booking.created",
                "booking.rescheduled",
                "booking.cancelled"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of event envelopes. A sample (no real events yet) has an id starting with evt_test_ and \"test\": true.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "event must be one of the event types",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key (send Authorization: Bearer <key> or X-API-Key) or invalid / revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: 120 per minute per key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/zapier/leads": {
      "post": {
        "operationId": "createLead",
        "summary": "Create a lead",
        "security": [
          {
            "apiKey": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "phone"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "address": {
                    "type": "string"
                  },
                  "service_needed": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "urgency": {
                    "type": "string",
                    "enum": [
                      "emergency",
                      "soon",
                      "standard",
                      "flexible"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The lead (source \"manual\")",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lead"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input, or \"Invalid JSON body\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key (send Authorization: Bearer <key> or X-API-Key) or invalid / revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request too large (the limit is 32 KB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: 120 per minute per key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/zapier/leads/search": {
      "get": {
        "operationId": "findLead",
        "summary": "Newest lead for a 10-digit US phone number (0 or 1 item)",
        "security": [
          {
            "apiKey": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array with zero or one lead",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Lead"
                  }
                }
              }
            }
          },
          "400": {
            "description": "phone must be a 10-digit US number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key (send Authorization: Bearer <key> or X-API-Key) or invalid / revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests: 120 per minute per key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Requests allowed per window (120)",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in this window",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}
