API Reference
Sitepins exposes two distinct API surfaces:
- Express REST Backend (
api/): Mounted on/api/v1(plus unversioned health checks). Handles database operations, authentication, permissions, and media storage. - Next.js Route Handlers (
app/src/app/api/): Server-side routes for Git provider code exchanges, AI processing, sandbox lifecycle orchestration, and project previews.
1. Express Backend Endpoints (/api/v1)
Unversioned System Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /healthz | Liveness & readiness probe. Returns { status: "ok", uptime: <seconds> }. |
GET | / | Returns Welcome to Sitepins API. |
Authentication (/api/v1/auth/*)
Powered by Better Auth:
POST /api/v1/auth/sign-up/email: Register with email and password (triggers verification OTP).POST /api/v1/auth/sign-in/email: Sign in with email and password.GET /api/v1/auth/callback/github: GitHub OAuth login callback.GET /api/v1/auth/callback/google: Google OAuth login callback.POST /api/v1/auth/verify-email: Confirm email address using 6-digit OTP.POST /api/v1/auth/forget-password: Request password reset email.POST /api/v1/auth/reset-password: Submit new password using reset token.GET /api/v1/auth/get-session: Retrieve current user session.POST /api/v1/auth/sign-out: Invalidate session and clear HTTP cookie.
User Management (/api/v1/user)
| Method | Endpoint | Auth Guard | Description |
|---|---|---|---|
GET | /:id | verifyAuth | Retrieve user profile by ID. |
PATCH | /set-password | verifyAuth | Update user password. |
PATCH | /update-country/:id | verifyAuth | Update user’s country of residence. |
DELETE | /delete/:id | verifyAuth | Permanently delete user account and cascade cleanups. |
Organization Management (/api/v1/organization)
| Method | Endpoint | Required Permission | Description |
|---|---|---|---|
GET | /user | verifyAuth | List all organizations the user belongs to. |
GET | /:org_id | org:VIEW_PROJECTS | Retrieve organization details and members. |
POST | / | verifyAuth | Create a new organization. |
POST | /ensure-default | verifyAuth | Create or return the user’s default fallback organization. |
PATCH | /member/:org_id | org:MANAGE_MEMBERS | Invite a new member by email. |
PATCH | /update-role/:org_id | org:MANAGE_MEMBERS | Update member role (admin, editor). |
PATCH | /remove-member/:org_id | org:MANAGE_MEMBERS | Remove a member from the organization. |
PATCH | /leave/:org_id | org:VIEW_MEMBERS | Leave an organization (members and admins; owners excluded). |
PATCH | /status/:org_id | org:MANAGE_ORG | Update organization status (active, archived). |
PATCH | /:org_id | org:MANAGE_ORG | Update organization name, thumbnail, or settings. |
DELETE | /:org_id | org:DELETE_ORG | Delete organization and its projects. |
User Preferences (/api/v1/user-preference)
| Method | Endpoint | Description |
|---|---|---|
GET | /:id | Retrieve user preferences (theme, language, timezone, Git co-authoring). |
PATCH | /theme/:id | Update color theme preference (light, dark, system). |
PATCH | /language/:id | Update interface language (15 supported locales). |
PATCH | /timezone/:id | Update local timezone setting. |
PATCH | /impersonate/:id | Update Git co-authoring attribution (personal vs bot). |
PATCH | /:id | Update combined preference attributes. |
Project Management (/api/v1/project)
| Method | Endpoint | Required Role | Description |
|---|---|---|---|
GET | /:projectId | owner, admin, editor | Get project metadata and settings. |
GET | /orgs/:orgId | owner, admin, editor | List all active projects in an organization. |
GET | /user/:userId | verifyAuth | List all projects across organizations owned by the user. |
POST | /create | owner, admin | Connect a new repository as a project. |
PATCH | /:projectId | owner, admin | Update project configuration (framework, paths). |
PATCH | /visibility/:projectId | owner, admin | Toggle public/private project visibility. |
PATCH | /status/:projectId | owner, admin | Update project status (active, archived). |
PATCH | /generator/:projectId | owner, admin | Update static site generator setting. |
PATCH | /git/:projectId | owner, admin | Update connected Git repository and working branch. |
PATCH | /move/:orgId/:projectId | org:DELETE_ORG | Move project to another organization. |
DELETE | /:projectId | org:MANAGE_PROJECTS | Delete a project. |
Live Preview Sandboxes (/api/v1/project-preview)
| Method | Endpoint | Auth Guard | Description |
|---|---|---|---|
GET | /:project_id | memberOfOrg | Retrieve active preview sandbox session metadata. |
PUT | /:project_id | memberOfOrg | Upsert sandbox session state and URLs. |
DELETE | /:project_id | memberOfOrg | Teardown recorded preview sandbox session. |
Git Provider Credentials (/api/v1/git-provider)
| Method | Endpoint | Auth Guard | Description |
|---|---|---|---|
POST | /create | verifyAuth | Save connected Git provider token. |
POST | /rotate | verifyAuth | Persist rotated OAuth tokens. |
GET | /:userId | verifyAuth | List connected Git providers for the user. |
Content & Activity Feeds
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/project-content/:project_id | Returns the indexed file tree of the project. |
GET | /api/v1/project-content/:project_id/file?file=<path> | Reads indexed file metadata. |
GET | /api/v1/project-log/:project_id | Retrieves recent file changes and Git activity. |
POST | /api/v1/project-log/:project_id | Records a file change event (create, update, delete). |
Media Uploads (/api/v1/bucket)
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/bucket/upload | Multipart file upload to S3 for avatars and project covers. |
DELETE | /api/v1/bucket/delete/:key | Delete asset by storage key. |
2. Next.js Route Handlers (app/api/)
These endpoints execute in the Next.js Node.js runtime and handle external API keys and long-running operations.
Git Provider OAuth & Token Refresh
| Method | Endpoint | Description |
|---|---|---|
POST | /api/auth/github | Exchanges the installation code for GitHub App access tokens. |
POST | /api/auth/github/refresh | Rotates an expiring GitHub App installation token. |
POST | /api/auth/gitlab | Exchanges the authorization code for a GitLab OAuth token. |
POST | /api/auth/gitlab/refresh | Rotates GitLab OAuth access tokens. |
AI Features (Streaming & BYOK)
| Method | Endpoint | Description |
|---|---|---|
POST | /api/ai/command | Streaming text generation/rewrite assistant for Plate rich-text editor. |
POST | /api/ai/copilot | Real-time inline ghost-text completions (≤50 tokens). |
POST | /api/ai/chat | Conversational assistant with project-wide context. |
POST | /api/ai/code-edit | Automated code refactoring and modifications with diff output. |
POST | /api/ai/code-explain | Explains code selections and templates. |
POST | /api/ai/commit | Generates semantic Git commit messages from staged diffs. |
POST | /api/ai/metadata | Automated SEO metadata and description extraction. |
POST | /api/ai/seo-fix | Automated SEO issue remediation. |
Live Preview Sandbox Control
| Method | Endpoint | Description |
|---|---|---|
POST | /api/sandbox/create | Initializes or connects to a Vercel Sandbox microVM (maxDuration = 600s). |
POST | /api/sandbox/heartbeat | Extends the sandbox timeout by 5 minutes during active sessions. |
POST | /api/sandbox/stop | Terminates and deallocates the preview sandbox. |
Standard Response Envelopes
Success Envelope
All Express responses return a consistent JSON wrapper:
{
"statusCode": 200,
"success": true,
"message": "Operation completed successfully",
"result": {
"project_id": "proj_abc123",
"name": "My Blog"
}
}Error Envelope
{
"message": "Validation failed",
"errorMessage": [
{
"path": "email",
"message": "Invalid email format"
}
]
}Last updated on