API Reference

API Architecture

All API routes are located in /app/api/ using Next.js App Router conventions.

Authentication

Most endpoints require Clerk authentication:

import { auth } from "@clerk/nextjs/server"

export async function GET() {
  const { userId, orgId } = await auth()
  if (!userId || !orgId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
  }
  // ...
}

Admin Endpoints

God Mode endpoints use additional guards:

import { requireGodMode, requireSuperAdmin } from "@/lib/admin-auth"

export async function GET() {
  await requireGodMode() // or requireSuperAdmin()
  // ...
}

Core API Routes

Organizations /api/organizations

Method	Path	Description
GET	/api/organizations	List user's organizations
POST	/api/organizations	Create organization
GET	/api/organizations/[id]	Get organization details
PATCH	/api/organizations/[id]	Update organization
DELETE	/api/organizations/[id]	Delete organization

Outreach /api/outreach

Method	Path	Description
GET	/api/outreach/contacts	List contacts
POST	/api/outreach/contacts	Create contact
GET	/api/outreach/sequences	List sequences
POST	/api/outreach/sequences	Create sequence
POST	/api/outreach/sequences/[id]/start	Start sequence

Scheduling /api/scheduling

Method	Path	Description
GET	/api/scheduling/profiles	List profiles
GET	/api/scheduling/availability	Get available slots
POST	/api/scheduling/bookings	Create booking

Social /api/social

Method	Path	Description
GET	/api/social/accounts	List connected accounts
POST	/api/social/posts	Create/schedule post
GET	/api/social/analytics	Get analytics data

Internal APIs (God Mode Only)

Admin /api/admin

Method	Path	Description
GET	/api/admin/stats	Platform statistics
GET	/api/admin/users	All users list
GET	/api/admin/organizations	All organizations
POST	/api/admin/impersonate	Impersonate user

System /api/system

Method	Path	Description
GET	/api/system/health	Health check
GET	/api/system/costs	AI cost analysis
POST	/api/system/cache/clear	Clear caches

Rate Limiting

Rate limits are enforced via middleware:

Tier	Requests/min	Burst
Free	60	10
Pro	300	50
Enterprise	1000	100
Internal	Unlimited	Unlimited

Error Handling

Standard error response format:

{
  "error": "Human readable message",
  "code": "ERROR_CODE",
  "details": {} // Optional additional info
}

HTTP Status Codes:

• 400 - Bad Request (validation failed)
• 401 - Unauthorized (not authenticated)
• 403 - Forbidden (no permission)
• 404 - Not Found
• 429 - Too Many Requests (rate limited)
• 500 - Internal Server Error