{
	"openapi": "3.1.0",
	"info": {
		"title": "VibeKit API",
		"description": "HTTP, REST, MCP, webhook, and tRPC gateway specifications for the VibeKit SaaS foundation.",
		"version": "1.0.0",
		"contact": {
			"name": "VibeKit Support",
			"email": "support@vibekit.dev",
			"url": "https://vibekit.dev"
		},
		"license": {
			"name": "Commercial License",
			"url": "https://vibekit.dev/pricing"
		}
	},
	"servers": [
		{
			"url": "/",
			"description": "Current host"
		}
	],
	"tags": [
		{ "name": "Health", "description": "System health and readiness probes" },
		{
			"name": "Authentication",
			"description": "Better Auth identity and session operations"
		},
		{
			"name": "MCP",
			"description": "Model Context Protocol endpoint for external AI agents"
		},
		{
			"name": "Storage",
			"description": "Managed upload and file asset endpoints"
		},
		{
			"name": "Webhooks",
			"description": "Payment and subscription provider webhooks"
		},
		{ "name": "tRPC", "description": "Application RPC boundary gateway" }
	],
	"paths": {
		"/api/health/live": {
			"get": {
				"tags": ["Health"],
				"summary": "Liveness Probe",
				"description": "Confirms the HTTP server process is running and accepting connections.",
				"responses": {
					"200": {
						"description": "Server is live",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"status": { "type": "string", "example": "ok" },
										"timestamp": { "type": "string", "format": "date-time" }
									},
									"required": ["status"]
								}
							}
						}
					}
				}
			}
		},
		"/api/health/ready": {
			"get": {
				"tags": ["Health"],
				"summary": "Readiness Probe",
				"description": "Verifies downstream connectivity to the database, storage, and external providers before admitting traffic.",
				"responses": {
					"200": {
						"description": "Server and dependencies are ready",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"status": { "type": "string", "example": "ready" },
										"database": { "type": "string", "example": "connected" },
										"timestamp": { "type": "string", "format": "date-time" }
									},
									"required": ["status", "database"]
								}
							}
						}
					},
					"503": {
						"description": "One or more dependencies are unready",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorResponse" }
							}
						}
					}
				}
			}
		},
		"/api/auth/sign-up/email": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Sign up with email and password",
				"description": "Creates a new user account with email and password credentials.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"email": { "type": "string", "format": "email" },
									"password": { "type": "string", "minLength": 8 },
									"name": { "type": "string" }
								},
								"required": ["email", "password", "name"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "User created and session cookie issued",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/AuthSessionResponse" }
							}
						}
					},
					"400": {
						"description": "Invalid input or user already exists",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorResponse" }
							}
						}
					}
				}
			}
		},
		"/api/auth/sign-in/email": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Sign in with email and password",
				"description": "Authenticates an existing user and issues a session cookie.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"email": { "type": "string", "format": "email" },
									"password": { "type": "string" }
								},
								"required": ["email", "password"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Authenticated successfully",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/AuthSessionResponse" }
							}
						}
					},
					"401": {
						"description": "Invalid credentials",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorResponse" }
							}
						}
					}
				}
			}
		},
		"/api/auth/sign-out": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Sign out session",
				"description": "Invalidates the active session and clears authentication cookies.",
				"security": [{ "sessionCookie": [] }],
				"responses": {
					"200": {
						"description": "Signed out successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": { "type": "boolean", "example": true }
									}
								}
							}
						}
					}
				}
			}
		},
		"/api/auth/get-session": {
			"get": {
				"tags": ["Authentication"],
				"summary": "Get active session",
				"description": "Returns the authenticated user record and active session metadata if present.",
				"security": [{ "sessionCookie": [] }],
				"responses": {
					"200": {
						"description": "Current session information",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/AuthSessionResponse" }
							}
						}
					}
				}
			}
		},
		"/api/auth/email-otp/send-verification-otp": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Send email OTP verification code",
				"description": "Dispatches a one-time verification code to the specified email address.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"email": { "type": "string", "format": "email" },
									"type": {
										"type": "string",
										"enum": ["sign-in", "email-verification", "forget-password"]
									}
								},
								"required": ["email", "type"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "OTP sent successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": { "type": "boolean", "example": true }
									}
								}
							}
						}
					}
				}
			}
		},
		"/api/auth/email-otp/verify-email": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Verify email OTP",
				"description": "Validates the one-time code to authenticate or verify an account.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"email": { "type": "string", "format": "email" },
									"otp": { "type": "string" }
								},
								"required": ["email", "otp"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Email verified successfully",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/AuthSessionResponse" }
							}
						}
					},
					"400": {
						"description": "Invalid or expired OTP",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorResponse" }
							}
						}
					}
				}
			}
		},
		"/api/auth/forget-password": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Request password reset",
				"description": "Sends a password reset token to the user email.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"email": { "type": "string", "format": "email" },
									"redirectTo": { "type": "string" }
								},
								"required": ["email"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Reset email dispatched",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"status": { "type": "boolean", "example": true }
									}
								}
							}
						}
					}
				}
			}
		},
		"/api/auth/reset-password": {
			"post": {
				"tags": ["Authentication"],
				"summary": "Reset password",
				"description": "Sets a new password using a verified reset token.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"token": { "type": "string" },
									"newPassword": { "type": "string", "minLength": 8 }
								},
								"required": ["token", "newPassword"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Password updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"status": { "type": "boolean", "example": true }
									}
								}
							}
						}
					}
				}
			}
		},
		"/api/mcp": {
			"post": {
				"tags": ["MCP"],
				"summary": "Model Context Protocol (MCP) JSON-RPC Gateway",
				"description": "Stream-capable JSON-RPC 2.0 endpoint enabling remote AI coding agents (Claude Desktop, Cursor, external tools) to query tools, resources, and prompts under authenticated OAuth/bearer grants.",
				"security": [{ "bearerAuth": [] }],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"jsonrpc": { "type": "string", "enum": ["2.0"] },
									"id": {
										"oneOf": [{ "type": "string" }, { "type": "number" }]
									},
									"method": { "type": "string", "example": "tools/list" },
									"params": { "type": "object" }
								},
								"required": ["jsonrpc", "method"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "JSON-RPC response or SSE event stream",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"jsonrpc": { "type": "string", "example": "2.0" },
										"id": {
											"oneOf": [{ "type": "string" }, { "type": "number" }]
										},
										"result": { "type": "object" },
										"error": { "type": "object" }
									}
								}
							}
						}
					},
					"401": {
						"description": "Missing or invalid bearer token grant",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/ErrorResponse" }
							}
						}
					}
				}
			}
		},
		"/api/storage/feedback": {
			"post": {
				"tags": ["Storage"],
				"summary": "Upload feedback attachment",
				"description": "Uploads user feedback images or screenshots into managed object storage.",
				"requestBody": {
					"required": true,
					"content": {
						"multipart/form-data": {
							"schema": {
								"type": "object",
								"properties": {
									"file": { "type": "string", "format": "binary" }
								},
								"required": ["file"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Attachment uploaded and URL resolved",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"url": { "type": "string", "format": "uri" },
										"id": { "type": "string" }
									},
									"required": ["url"]
								}
							}
						}
					}
				}
			}
		},
		"/api/storage/s3": {
			"post": {
				"tags": ["Storage"],
				"summary": "S3 multipart presigned upload handler",
				"description": "Issues signed upload instructions for direct S3-compatible client uploads.",
				"security": [{ "sessionCookie": [] }],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"filename": { "type": "string" },
									"contentType": { "type": "string" },
									"size": { "type": "number" }
								},
								"required": ["filename", "contentType", "size"]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Presigned URL and upload token issued",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"uploadUrl": { "type": "string", "format": "uri" },
										"fileKey": { "type": "string" }
									}
								}
							}
						}
					}
				}
			}
		},
		"/api/storage/vercel-blob": {
			"post": {
				"tags": ["Storage"],
				"summary": "Vercel Blob client upload handler",
				"description": "Authorizes and finalizes client uploads targeted to Vercel Blob.",
				"security": [{ "sessionCookie": [] }],
				"responses": {
					"200": {
						"description": "Upload client token generated"
					}
				}
			}
		},
		"/api/webhooks/stripe": {
			"post": {
				"tags": ["Webhooks"],
				"summary": "Stripe webhook receiver",
				"description": "Receives signed Stripe subscription, checkout, and invoice lifecycle events.",
				"security": [{ "webhookSignature": [] }],
				"responses": {
					"200": {
						"description": "Webhook processed successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"received": { "type": "boolean", "example": true }
									}
								}
							}
						}
					},
					"400": {
						"description": "Invalid signature or malformed payload"
					}
				}
			}
		},
		"/api/webhooks/lemonsqueezy": {
			"post": {
				"tags": ["Webhooks"],
				"summary": "Lemon Squeezy webhook receiver",
				"description": "Processes Lemon Squeezy order and subscription lifecycle events.",
				"security": [{ "webhookSignature": [] }],
				"responses": {
					"200": { "description": "Webhook processed successfully" }
				}
			}
		},
		"/api/webhooks/paddle": {
			"post": {
				"tags": ["Webhooks"],
				"summary": "Paddle webhook receiver",
				"description": "Processes Paddle transaction, subscription, and billing notifications.",
				"security": [{ "webhookSignature": [] }],
				"responses": {
					"200": { "description": "Webhook processed successfully" }
				}
			}
		},
		"/api/webhooks/polar": {
			"post": {
				"tags": ["Webhooks"],
				"summary": "Polar webhook receiver",
				"description": "Processes Polar one-time and recurring order webhook payloads.",
				"security": [{ "webhookSignature": [] }],
				"responses": {
					"200": { "description": "Webhook processed successfully" }
				}
			}
		},
		"/api/webhooks/dodopayments": {
			"post": {
				"tags": ["Webhooks"],
				"summary": "Dodo Payments webhook receiver",
				"description": "Processes Dodo Payments subscription and transaction webhook payloads.",
				"security": [{ "webhookSignature": [] }],
				"responses": {
					"200": { "description": "Webhook processed successfully" }
				}
			}
		},
		"/api/trpc/{procedure}": {
			"get": {
				"tags": ["tRPC"],
				"summary": "tRPC Query Gateway",
				"description": "Executes batchable typed tRPC queries. Procedure name is passed in the path, with URI-encoded input parameters in the query string.",
				"parameters": [
					{
						"name": "procedure",
						"in": "path",
						"required": true,
						"description": "Target procedure path (e.g., `admin.systemStats`, `team.dashboardStats`)",
						"schema": { "type": "string" }
					},
					{
						"name": "input",
						"in": "query",
						"required": false,
						"description": "URL-encoded JSON input envelope adhering to the procedure Zod schema",
						"schema": { "type": "string" }
					}
				],
				"responses": {
					"200": {
						"description": "tRPC result envelope",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"result": {
											"type": "object",
											"properties": {
												"data": { "type": "object" }
											}
										}
									}
								}
							}
						}
					},
					"400": { "description": "BAD_REQUEST or schema validation failure" },
					"401": {
						"description": "UNAUTHORIZED - Missing authenticated session"
					},
					"403": {
						"description": "FORBIDDEN - Caller lacks team membership or required role"
					},
					"404": { "description": "NOT_FOUND - Foreign or missing resource" }
				}
			},
			"post": {
				"tags": ["tRPC"],
				"summary": "tRPC Mutation Gateway",
				"description": "Executes typed tRPC mutations with automatic abuse throttling and database transaction encapsulation.",
				"parameters": [
					{
						"name": "procedure",
						"in": "path",
						"required": true,
						"description": "Target mutation procedure path (e.g., `ai.copilotQuery`, `team.inviteMember`)",
						"schema": { "type": "string" }
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"description": "Procedure payload validated by owning feature Zod contract"
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Mutation result envelope",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"result": {
											"type": "object",
											"properties": {
												"data": { "type": "object" }
											}
										}
									}
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"securitySchemes": {
			"sessionCookie": {
				"type": "apiKey",
				"in": "cookie",
				"name": "better-auth.session_token",
				"description": "Encrypted HTTP-only Better Auth session cookie"
			},
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "Token",
				"description": "API token or MCP OAuth access grant token"
			},
			"webhookSignature": {
				"type": "apiKey",
				"in": "header",
				"name": "Stripe-Signature",
				"description": "Provider cryptographic HMAC signature header"
			}
		},
		"schemas": {
			"User": {
				"type": "object",
				"properties": {
					"id": { "type": "string" },
					"email": { "type": "string", "format": "email" },
					"name": { "type": "string" },
					"image": { "type": "string", "nullable": true },
					"role": { "type": "string", "enum": ["user", "admin"] },
					"createdAt": { "type": "string", "format": "date-time" }
				},
				"required": ["id", "email", "name"]
			},
			"Session": {
				"type": "object",
				"properties": {
					"id": { "type": "string" },
					"userId": { "type": "string" },
					"expiresAt": { "type": "string", "format": "date-time" }
				},
				"required": ["id", "userId", "expiresAt"]
			},
			"AuthSessionResponse": {
				"type": "object",
				"properties": {
					"user": { "$ref": "#/components/schemas/User" },
					"session": { "$ref": "#/components/schemas/Session" }
				},
				"required": ["user", "session"]
			},
			"ErrorResponse": {
				"type": "object",
				"properties": {
					"message": { "type": "string" },
					"code": { "type": "string" },
					"status": { "type": "number" }
				},
				"required": ["message"]
			}
		}
	}
}