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. The full secret is not returned.

{
  "keys": [
    { "id": 1, "key": null, "keyPreview": "mk_abcd1…9xyz", "label": "Production", "is_active": true, "created_at": "2026-03-01T12:00:00Z" }
  ]
}

Generate a new API key. The full key value is returned only in this response.

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"

Create a poll (host). pollType is one of multiple_choice, yes_no, rating.

curl -X POST https://onepizza.io/api/meetings/abc-defg-hij/polls \
  -H "x-api-key: YOUR_KEY" -H "x-admin-token: ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pollType":"multiple_choice","question":"Lunch?","options":["Pizza","Tacos"]}'

Cast a vote. Body: { "vote": 0 } (option index; legacy opt_N ids also accepted).

Close a poll and reveal results (host).

List polls with current tallies.

Submit a question. Body: { "text": "..." }.

Upvote a question (one per participant).

Mark a question answered (host).

Dismiss a question (host).

List questions sorted by upvotes.

Fetch the current collaborative notes for a meeting.

Replace the notes (host). Body: { "content": "..." } (max 10,000 chars).

Upload a file to share in the meeting (multipart/form-data, field file). Stored via the configured storage backend (local disk or S3).

List files shared in the meeting.

Download a shared file by ID.

Per-participant join/leave/duration report (host).

Download the attendance report as a file (host).

List your meeting templates (plus seeded defaults).

Create a template. Body: { "name": "string", "title": "string", "settings": {} } — only name is required (session auth).

Update a template (session auth).

Delete a template (session auth).

List recurring meeting schedules. Legacy alias: GET /api/meetings/recurring returns deprecation headers and points to this endpoint.

Create a recurring schedule. Body: { "title": "string", "rrule": "string", "timezone": "string", "settings": {} } — title and rrule are required, timezone defaults to UTC (iCal RRULE). Legacy alias: POST /api/meetings/recurring.

Update a recurring schedule. Legacy alias: PUT /api/meetings/recurring/:id.

Delete a recurring schedule. (Alias: DELETE /api/meetings/recurring/:id.)

Reports whether LiveKit is enabled, its URL, the advisory threshold (SFU_PARTICIPANT_THRESHOLD, default 8), meshParticipantCap, roomParticipantCap, sfuMaxParticipants, and whether the bundled client has SFU media integration.

Mints a short-lived LiveKit access token (4h TTL) for a participant, authenticated by the per-participant sfuAuthToken issued at join.

Starts LiveKit room-composite egress to an rtmp://, rtmps://, or srt:// destination. Requires the meeting admin token.

Accepts periodic client quality samples (media mode, RTT, jitter, loss, bitrate, peer count) authenticated by the live participant token. Hosts can read recent samples with GET /api/meetings/:meetingId/quality.

Full health check — verifies database connectivity.

// 200 OK
{ "status": "ok", "uptime": 123.45, "timestamp": "2026-06-30T12:00:00.000Z", "meetings": 0 }

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

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

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

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

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

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