API Reference

Complete endpoint documentation — 20+ routes

All API routes are Next.js 15 App Router API handlers. Authentication is enforced via Clerk middleware. Click any endpoint to expand request/response details.

Hostel Intelligence

AI-powered discovery, enrichment, and intelligence generation.

POST/api/hostels/searchAI-powered hostel discovery with verification pipeline

AI-powered hostel discovery with verification pipeline

Request Body

{
  "location": "Bali, Indonesia",
  "skills": ["marketing", "SEO", "content"],
  "userId": "user_2x4k..."
}

Response

{
  "hostels": [
    {
      "name": "The Mad Monkey",
      "location": "Ubud, Bali",
      "website": "https://themadmonkey.com",
      "websiteVerified": true,
      "contactEmail": "info@themadmonkey.com",
      "emailVerified": true,
      "matchScore": 87,
      "needs": ["social media", "SEO"]
    }
  ],
  "cached": false
}

POST/api/hostels/search/enrichVerify and enrich hostel contact information

Verify and enrich hostel contact information

Request Body

{
  "hostels": [
    { "name": "...", "website": "..." }
  ]
}

POST/api/hostels/dossierGenerate AI intelligence report + personalized pitch

Generate AI intelligence report + personalized pitch

Request Body

{
  "hostelName": "The Mad Monkey",
  "hostelWebsite": "https://themadmonkey.com",
  "userName": "Jaryd",
  "userHeadline": "Full-Stack Developer & AI Engineer",
  "userSkills": ["SEO", "Web Dev", "AI Automation"],
  "userBio": "...",
  "userLocation": "Cape Town, SA"
}

Response

{
  "dossier": "## Market Snapshot\n...",
  "pitch": "Hi [Name],\n...",
  "verifiedEmails": ["info@themadmonkey.com"],
  "scrapedEmails": ["bookings@themadmonkey.com"]
}

Proposals

Create, manage, and track skill-exchange proposals.

GET/api/proposalsList user's proposals (as nomad or hostel)

List user's proposals (as nomad or hostel)

Response

{
  "proposals": [
    {
      "id": "uuid",
      "hostel_name": "The Mad Monkey",
      "status": "pending",
      "terms": { "duration": "2 weeks", "accommodation": "private room" },
      "created_at": "2026-03-26T..."
    }
  ]
}

POST/api/proposalsCreate proposal and send email to hostel

Create proposal and send email to hostel

Request Body

{
  "hostel_name": "The Mad Monkey",
  "hostel_id": "hostel-slug",
  "terms": {
    "duration": "2 weeks",
    "deliverables": ["Social media audit", "30 posts"],
    "accommodation": "private room"
  },
  "initial_message": "Hi, I'd love to...",
  "recipient_email": "info@themadmonkey.com",
  "send_email": true
}

PATCH/api/proposalsUpdate proposal status (accept, reject, negotiate)

Update proposal status (accept, reject, negotiate)

Request Body

{
  "id": "uuid",
  "status": "accepted"
}

Unified Inbox

Full email lifecycle — connect, sync, read, compose, reply.

GET/api/inbox/accountsList connected email accounts for the authenticated user

List connected email accounts for the authenticated user

POST/api/inbox/connect/:provider/startInitiate OAuth flow — redirects to Google/Microsoft consent screen

Initiate OAuth flow — redirects to Google/Microsoft consent screen

GET/api/inbox/connect/:provider/callbackHandle OAuth callback — exchanges code for tokens, stores in DB

Handle OAuth callback — exchanges code for tokens, stores in DB

POST/api/inbox/syncTrigger email synchronization (kicks off Inngest job)

Trigger email synchronization (kicks off Inngest job)

GET/api/inbox/threadsList email threads with pagination, filtering, and sorting

List email threads with pagination, filtering, and sorting

Response

{
  "threads": [
    {
      "id": "uuid",
      "subject": "Re: Marketing Proposal",
      "snippet": "Thanks for reaching out...",
      "is_unread": true,
      "last_message_at": "2026-03-26T..."
    }
  ]
}

GET/api/inbox/threads/:idGet full thread with all messages, attachments, and metadata

Get full thread with all messages, attachments, and metadata

POST/api/inbox/threads/:id/replyReply to a thread via connected email account

Reply to a thread via connected email account

Request Body

{
  "body": "Thanks for getting back to me...",
  "accountId": "uuid"
}

POST/api/inbox/threads/:id/archiveArchive a thread

Archive a thread

POST/api/inbox/threads/:id/starStar or unstar a thread

Star or unstar a thread

POST/api/inbox/threads/:id/mark-readMark thread as read

Mark thread as read

POST/api/inbox/sendSend a new email (used by proposal system)

Send a new email (used by proposal system)

Request Body

{
  "to": "hostel@example.com",
  "subject": "Marketing Proposal — HostelHack",
  "body": "<html>...</html>",
  "accountId": "uuid"
}

POST/api/inbox/draftSave an email draft

Save an email draft

GET/api/inbox/unread-countGet count of unread emails across all connected accounts

Get count of unread emails across all connected accounts

GET/api/inbox/searchFull-text search across email threads

Full-text search across email threads

Webhooks

Real-time push notifications from email providers.

POST/api/webhooks/gmailGmail Pub/Sub push notification handler — triggers delta sync

Gmail Pub/Sub push notification handler — triggers delta sync

POST/api/webhooks/microsoft-graphMicrosoft Graph change notification handler — validates subscription + triggers delta sync

Microsoft Graph change notification handler — validates subscription + triggers delta sync