onepizza.io API

Create a new account. Returns the account API key. A welcome email is sent if RESEND_API_KEY is configured.

curl -X POST /api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret123"}'

# Response
{
  "message": "Account created",
  "email": "you@example.com",
  "apiKey": "mk_abc123...",
  "accountType": "personal"
}

Log in to your account. Sets a session cookie used by the dashboard.

Destroy the current session and clear the session cookie.

Get the current authenticated user's profile. Used by the dashboard to verify login state.

{
  "id": 42,
  "email": "you@example.com",
  "accountType": "personal",
  "balance": "25.0000",
  "company_id": null,
  "is_admin": false,
  "created_at": "2026-03-01T12:00:00Z"
}

Request a password reset email. Rate-limited to 3 requests per 15 minutes per IP. Silently succeeds even if email not found (prevents user enumeration).

Validate a password reset token. Called client-side to check if the token from the email link is still valid (tokens expire after 1 hour).

Set a new password using a valid reset token.

Change the current user's password. Requires authentication. Sends a "password changed" security email on success.

List all API keys for the current user.

{
  "keys": [
    { "id": 1, "key": "mk_abc123...", "label": "Production", "is_active": true, "created_at": "2026-03-01T12:00:00Z" }
  ]
}

Generate a new API key.

Revoke and permanently delete an API key. Any requests using the deleted key will immediately return 401.

Create a new meeting (instant or scheduled). Requires an active API key. Credits are deducted when the meeting ends based on duration and peak participant count.

# Instant meeting
curl -X POST /api/meetings \
  -H "Content-Type: application/json" \
  -H "x-api-key: mk_yourkey" \
  -d '{"title": "Team Standup"}'

# Response
{
  "meetingId": "abc-defg-hij",
  "adminToken": "d4e5f6...",
  "joinUrl": "/join/abc-defg-hij",
  "title": "Team Standup",
  "status": "active",
  "settings": { "muteOnJoin": false, "videoOffOnJoin": false, "maxParticipants": 50, "locked": false, "waitingRoom": false }
}

# Scheduled meeting
curl -X POST /api/meetings \
  -H "Content-Type: application/json" \
  -H "x-api-key: mk_yourkey" \
  -d '{"title":"Weekly Sync","scheduledAt":"2026-04-01T14:00:00Z"}'

# Response
{
  "meetingId": "xyz-abcd-efg",
  "adminToken": "a1b2c3...",
  "joinUrl": "/join/xyz-abcd-efg",
  "title": "Weekly Sync",
  "scheduledAt": "2026-04-01T14:00:00.000Z",
  "status": "scheduled",
  "settings": { "muteOnJoin": false, "videoOffOnJoin": false, "maxParticipants": 50, "locked": false, "waitingRoom": false }
}

List all currently active and scheduled meetings for the authenticated API key's user.

{
  "meetings": [
    { "meetingId": "abc-defg-hij", "title": "Team Standup", "status": "active", "participantCount": 3, "createdAt": 1710000000000 },
    { "meetingId": "xyz-abcd-efg", "title": "Weekly Sync", "status": "scheduled", "scheduledAt": "2026-04-01T14:00:00.000Z", "participantCount": 0 }
  ]
}

Get details of a specific meeting including current participants and settings.

{
  "meetingId": "abc-defg-hij",
  "title": "Team Standup",
  "status": "active",
  "createdAt": 1710000000000,
  "participantCount": 2,
  "participants": [
    { "participantId": "a1b2c3", "name": "Alice", "isMuted": false, "isVideoOff": false, "isScreenSharing": false, "joinedAt": 1710000001000 }
  ],
  "settings": { "muteOnJoin": false, "videoOffOnJoin": false, "maxParticipants": 50, "locked": false, "waitingRoom": false }
}

End a meeting, disconnect all participants, and trigger billing. Requires x-admin-token.

curl -X DELETE /api/meetings/abc-defg-hij \
  -H "x-api-key: mk_yourkey" \
  -H "x-admin-token: d4e5f6..."

Create a guest meeting with no API key. Limited to 5 meetings per hour per IP address. This endpoint powers the homepage "Start a meeting" button.

curl -X POST /api/meetings/guest \
  -H "Content-Type: application/json" \
  -d '{"title": "Quick Sync"}'

# Response
{
  "meetingId": "qwerty-abc",
  "adminToken": "uuid...",
  "joinUrl": "/join/qwerty-abc",
  "title": "Quick Sync"
}

List all scheduled (not yet started) meetings for the authenticated API key's user.

curl /api/meetings/scheduled/list -H "x-api-key: mk_yourkey"

# Response
{
  "meetings": [
    { "meetingId": "xyz-abcd-efg", "title": "Weekly Sync", "scheduledAt": "2026-04-01T14:00:00.000Z", "status": "scheduled", "createdAt": 1710000000000 }
  ]
}

Update meeting settings live. Changes are broadcast to all participants via the meeting:settings-updated Socket.IO event.

Lock the meeting — no new participants can join until unlocked.

Unlock the meeting, allowing participants to join again.

Generate a one-use invite link for a new participant.

{
  "joinUrl": "/join/abc-defg-hij?invite=x1y2z3&name=Bob",
  "inviteToken": "x1y2z3"
}

Force-mute a specific participant. The participant receives an admin:mute event and their audio is disabled client-side.

Send an unmute request to a specific participant.

Remove a participant immediately. They receive an admin:kick event with a reason.

Mute every participant simultaneously. Broadcasts meeting:all-muted to the room.

Get the meeting usage history for the authenticated user (or their company). Includes duration, peak participants, and credit cost per meeting.

curl /api/meetings/history -b session_cookie

# Response
{
  "meetings": [
    {
      "id": 1,
      "meeting_id": "abc-defg-hij",
      "title": "Team Standup",
      "started_at": "2026-03-19T10:00:00Z",
      "ended_at": "2026-03-19T10:30:00Z",
      "duration_minutes": "30.00",
      "peak_participants": 4,
      "cost_usd": "0.0120"
    }
  ]
}

List all configured webhook endpoints for the current user.

{
  "webhooks": [
    { "id": 1, "url": "https://your-app.com/webhook", "events": ["meeting.ended","participant.left"], "created_at": "2026-03-01T12:00:00Z" }
  ]
}

Register a new webhook endpoint.

Available Events

Webhook Payload

{
  "event": "meeting.ended",
  "meetingId": "abc-defg-hij",
  "timestamp": 1710000000000,
  "data": {
    "title": "Team Standup",
    "durationMinutes": 30,
    "peakParticipants": 4,
    "costUsd": "0.0120"
  }
}

Remove a webhook endpoint. Events will no longer be sent to that URL.

Returns the STUN/TURN server list used for WebRTC. The web client calls this automatically on join. If TURN credentials are configured via environment variables, they are included here.

# Default response (STUN only)
{
  "iceServers": [
    { "urls": "stun:stun.l.google.com:19302" },
    { "urls": "stun:stun1.l.google.com:19302" }
  ]
}

# With TURN configured
{
  "iceServers": [
    { "urls": "stun:stun.l.google.com:19302" },
    { "urls": "turn:your-turn-server.com:3478", "username": "...", "credential": "..." }
  ]
}

Create a company account by setting accountType: "company". An invite code is returned, which members use to join.

curl -X POST /api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@acme.com","password":"secret123","accountType":"company","companyName":"Acme Corp"}'

# Response
{
  "message": "Account created",
  "email": "owner@acme.com",
  "apiKey": "mk_abc123...",
  "inviteCode": "aBcDeFgHiJkL",
  "accountType": "company"
}

Join an existing company workspace using an invite code. The user's balance merges into the company balance.

curl -X POST /api/company/join \
  -H "Content-Type: application/json" \
  -b session_cookie \
  -d '{"inviteCode": "aBcDeFgHiJkL"}'

# Response
{ "message": "Joined Acme Corp", "companyId": 1, "companyName": "Acme Corp" }

List all members of the current user's company. Only available to company account owners.

{
  "members": [
    { "id": 1, "email": "owner@acme.com", "role": "owner", "joined_at": "2026-03-01T12:00:00Z" },
    { "id": 2, "email": "dev@acme.com", "role": "member", "joined_at": "2026-03-05T08:00:00Z" }
  ]
}

Remove a member from the company. Only the company owner can do this.

Create a Stripe Checkout session to top up credits via credit/debit card. Redirects the user to Stripe's hosted checkout page.

curl -X POST /api/billing/stripe/checkout \
  -H "Content-Type: application/json" \
  -b session_cookie \
  -d '{"amountUsd": 20}'

# Response
{ "url": "https://checkout.stripe.com/c/pay/..." }

Get the USDC (ERC-20) deposit address for your account. Each user/company gets a unique HD wallet address derived from the server's mnemonic. Send USDC on Ethereum mainnet to this address — the server polls for deposits and credits your balance automatically.

curl /api/billing/usdc/address -b session_cookie

# Response
{ "address": "0xABC123..." }

Get balance and transaction history for the current user or their company.

{
  "balance": "25.0000",
  "transactions": [
    { "id": 1, "amount_usd": "20.0000", "type": "stripe_topup", "description": "Stripe top-up $20", "created_at": "2026-03-10T12:00:00Z" },
    { "id": 2, "amount_usd": "-0.0120", "type": "meeting_charge", "description": "Meeting abc-defg-hij (30m, 4 participants)", "created_at": "2026-03-19T10:30:00Z" }
  ]
}

Stripe webhook receiver (internal use). Credits are added automatically when Stripe confirms a payment. Configured via STRIPE_WEBHOOK_SECRET.

Feature usage breakdown for tracked events (screen share, recording, chat, reactions, etc.).

# Response
{
  "features": [
    { "feature": "screen_share", "total_uses": 142, "unique_users": 38, "active_days": 22 },
    { "feature": "recording", "total_uses": 67, "unique_users": 15, "active_days": 18 }
  ],
  "days": 30
}

Aggregated error log grouped by event type, route, and message.

# Response
{
  "errors": [
    { "event_type": "error.webrtc", "route": "/join", "message": "ICE connection failed", "count": 12, "last_seen": "2026-03-20T14:30:00Z" }
  ],
  "days": 30
}

Live meeting state from server memory (no DB query). Shows all currently active meetings and aggregate counts.

# Response
{
  "activeMeetings": 3,
  "totalParticipants": 14,
  "activeRecordings": 1,
  "activeScreenShares": 2,
  "meetingList": [
    { "id": "abc-defg-hij", "title": "Team Standup", "participantCount": 5, "duration": 1200, "isRecording": true }
  ]
}

Week-over-week user retention for the last 12 weeks.

# Response
{
  "retention": [
    { "week": "2026-03-10", "users": 120, "retained": 84 },
    { "week": "2026-03-03", "users": 115, "retained": 79 }
  ]
}

Server health metrics including memory usage, DB pool stats, and active meeting counts.

# Response
{
  "uptimeSeconds": 86400,
  "memoryMB": 128.5,
  "heapUsedMB": 95.2,
  "heapTotalMB": 140.0,
  "dbPoolTotal": 20,
  "dbPoolIdle": 15,
  "dbPoolWaiting": 0,
  "activeMeetings": 3,
  "scheduledMeetings": 1
}

Meeting distribution by day-of-week and hour. Useful for capacity planning.

# Response
{
  "peakHours": [
    { "dow": 1, "hour": 10, "count": 45 },
    { "dow": 3, "hour": 14, "count": 38 }
  ],
  "days": 90
}

Get the full chat transcript for a meeting as JSON.

curl https://onepizza.io/api/meetings/abc-defg-hij/transcript \
  -H "x-api-key: YOUR_KEY"

# Response:
{
  "messages": [
    { "participant_name": "Alice", "text": "Hello everyone!", "created_at": "2026-03-22T14:30:00Z" },
    { "participant_name": "Bob", "text": "Hi Alice!", "created_at": "2026-03-22T14:30:05Z" }
  ]
}

Download the chat transcript as a plain text file. Returns Content-Disposition: attachment.

curl -O https://onepizza.io/api/meetings/abc-defg-hij/transcript/download \
  -H "x-api-key: YOUR_KEY"

# Downloaded file format:
# [14:30:00] Alice: Hello everyone!
# [14:30:05] Bob: Hi Alice!

Upload a recording file (multipart/form-data). Max file size: 500 MB. Accepts video/* and audio/* MIME types.

curl -X POST https://onepizza.io/api/meetings/abc-defg-hij/recordings \
  -H "x-api-key: YOUR_KEY" \
  -F "recording=@meeting-recording.webm"

# Response (201):
{
  "id": 1,
  "filename": "meeting-recording.webm",
  "size_bytes": 15728640,
  "created_at": "2026-03-22T15:00:00Z"
}

List all recordings for a meeting.

curl https://onepizza.io/api/meetings/abc-defg-hij/recordings \
  -H "x-api-key: YOUR_KEY"

# Response:
{
  "recordings": [
    { "id": 1, "filename": "meeting-recording.webm", "size_bytes": 15728640, "created_at": "2026-03-22T15:00:00Z" }
  ]
}

Download a recording file by ID. Returns the file with Content-Disposition: attachment.

curl -O https://onepizza.io/api/recordings/1/download \
  -H "x-api-key: YOUR_KEY"

Full health check — verifies database connectivity.

// 200 OK
{ "status": "ok", "db": "connected" }

// 503 Service Unavailable
{ "status": "error", "db": "unavailable" }

Liveness probe — always returns 200 if the process is running. Use for Kubernetes liveness checks.

// 200 OK
{ "status": "alive" }

Readiness probe — returns 200 only if the database is reachable. Use for Kubernetes readiness checks and load balancer health.

// 200 OK
{ "status": "ready", "db": "connected" }

// 503 Service Unavailable
{ "status": "not ready", "db": "unavailable" }