API Reference

VibeKit provides two distinct API boundaries:

Application RPC (tRPC): The internal typed boundary used by the web client and server actions under /api/trpc.
Standard HTTP/REST & MCP: Public endpoints for authentication (/api/auth), health monitoring (/api/health), file uploads (/api/storage), payment webhooks (/api/webhooks), and Model Context Protocol agent connectivity (/api/mcp).

The machine-readable specification is available at /openapi.json and via the dynamic endpoint /api/openapi.json.

OpenAPI Specification

The OpenAPI 3.1.0 document describes all external HTTP, REST, webhook, and gateway endpoints.

Direct download: /openapi.json
Dynamic API route: /api/openapi.json
Specification version: 3.1.0

You can import this specification directly into API tools such as Postman, Insomnia, Swagger UI, or Scalar.

Authentication Schemes

VibeKit enforces authorization on the server. UI visibility controls are never treated as security boundaries.

Scheme	Transport	Header / Cookie	Purpose
Session Cookie	Cookie	`better-auth.session_token`	Authenticated browser sessions across web app routes
Bearer Token	HTTP Header	`Authorization: Bearer TOKEN`	Remote MCP client sessions and API tokens
Webhook HMAC	HTTP Header	`Stripe-Signature` / Provider secret	Verifies incoming payment lifecycle events

Health Probes

Health endpoints expose machine-checkable status for container orchestrators, load balancers, and uptime monitors.

Liveness Probe

Confirms the process is running and accepting HTTP connections. It never probes downstream databases or third-party providers.

curl -i https://your-domain.com/api/health/live

Response (200 OK):

{
  "status": "ok"
}

Readiness Probe

Probes internal dependencies (PostgreSQL database, storage, email) before admitting live traffic.

curl -i https://your-domain.com/api/health/ready

Response (200 OK):

{
  "status": "ready",
  "database": "connected",
  "timestamp": "2026-09-12T18:00:00.000Z"
}

Authentication Endpoints (Better Auth)

Authentication endpoints handle user credential flows, OTP dispatch, session inspection, and password resets under /api/auth.

Method	Endpoint	Description
`POST`	`/api/auth/sign-up/email`	Create new account with email and password
`POST`	`/api/auth/sign-in/email`	Authenticate existing user credentials
`POST`	`/api/auth/sign-out`	Invalidate active session and clear cookies
`GET`	`/api/auth/get-session`	Return current authenticated user and session
`POST`	`/api/auth/email-otp/send-verification-otp`	Dispatch one-time email verification code
`POST`	`/api/auth/email-otp/verify-email`	Verify one-time code and confirm email
`POST`	`/api/auth/forget-password`	Request password reset token
`POST`	`/api/auth/reset-password`	Set new password with validated reset token

curl -X POST https://your-domain.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securepassword123"}'

Model Context Protocol (MCP)

VibeKit provides a remote MCP server at /api/mcp allowing external AI agents (such as Claude Desktop or Cursor) to securely inspect product context and invoke permitted tools.

Protocol: JSON-RPC 2.0 over HTTP and Server-Sent Events (SSE).
Authentication: Bearer token issued via OAuth consent flow (features/mcp).
Authorization: Scoped by explicit user consent (api:read, api:write).

curl -X POST https://your-domain.com/api/mcp \
  -H "Authorization: Bearer <mcp-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Storage & Uploads

Managed file uploads follow an explicit lifecycle:

issue -> upload -> finalize -> claim -> resolve -> delete

Method	Endpoint	Description
`POST`	`/api/storage/feedback`	Multipart upload for feedback screenshots and reports
`POST`	`/api/storage/s3`	Presigned URL issuer for direct S3-compatible uploads
`POST`	`/api/storage/vercel-blob`	Client token issuer for Vercel Blob storage

Payment Webhooks

Payment webhooks receive asynchronous lifecycle notifications from billing providers. Every webhook endpoint validates the provider's cryptographic signature before admitting payloads.

Method	Endpoint	Supported Provider
`POST`	`/api/webhooks/stripe`	Stripe payments and subscriptions
`POST`	`/api/webhooks/lemonsqueezy`	Lemon Squeezy orders and subscriptions
`POST`	`/api/webhooks/paddle`	Paddle billing transactions
`POST`	`/api/webhooks/polar`	Polar products and subscriptions
`POST`	`/api/webhooks/dodopayments`	Dodo Payments transactions

Application RPC (tRPC Gateway)

Internal web application features interact through the typed tRPC router at /api/trpc.

Queries (GET /api/trpc/:procedure): URL-encoded JSON parameters passed via the ?input= query string.
Mutations (POST /api/trpc/:procedure): JSON payload in the request body.
Batching: Supported natively by the tRPC client link.

Standard error envelope:

{
  "error": {
    "message": "UNAUTHORIZED",
    "code": -32001,
    "data": {
      "code": "UNAUTHORIZED",
      "httpStatus": 401
    }
  }
}

Agent-First Instructions

Give your coding agent this prompt when extending or modifying API endpoints:

Use the existing Zod/tRPC patterns in packages/api to add the required procedure.
Validate all bounded inputs and outputs.
Enforce server-side authentication, role, and Team membership checks.
Update apps/web/public/openapi.json if adding a public HTTP/REST route, and verify with $verify-changes.

API Reference

On this page