API Reference

REST API endpoints and integration patterns.

Overview

The LokkoLabs API uses Next.js API routes with a consistent response format. Authentication varies by endpoint type.

Base URL

https://lokkolabs.com/api

Response Format

// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "success": false,
  "error": "Error message"
}

Authentication

Two authentication modes are used:

Session Auth

For organizers, admins, and company members. Uses Supabase Auth cookies.

Cookie: sb-xxx-auth-token

Event Code

For attendee-facing endpoints. Event code in URL path.

/api/events/{code}/...

Event Endpoints

Get Event by Code

GET/api/events/{code}

Get event details by access code. Public endpoint for attendees.

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "code": "FALCON-42",
    "name": "Team Building Event",
    "phase": "training",
    "startedAt": "2024-01-15T10:00:00Z"
  }
}

Join Event

POST/api/events/{code}/join

Request:

{
  "name": "John Smith",
  "email": "john@example.com",
  "experienceLevel": "beginner"
}

Response:

{
  "success": true,
  "data": {
    "attendeeId": "uuid",
    "codename": "Shadow Falcon",
    "agentNumber": 42,
    "coverJob": "Artisanal Cheese Whisperer",
    "teamColor": "red",
    "teamTable": 1
  }
}

Get Attendee State

GET/api/events/{code}/attendees/{id}

Get current attendee state including phase progress.

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "phaseStatus": "training",
    "progress": 0.65,
    "teamId": "uuid",
    "lastActivityAt": "2024-01-15T10:30:00Z"
  }
}

Submit Help Request

POST/api/events/{code}/help-request

Submit a help request from an attendee.

Request:

{
  "attendeeId": "uuid",
  "message": "Lock is stuck"
}

Organizer Endpoints

Require organizer role or higher.

Advance Phase

POST/api/organizer/events/{id}/phase

Advance the event to the next phase.

Request:

{
  "targetPhase": "training"
}

Record Team Completion

POST/api/organizer/events/{id}/teams/{teamId}/complete

Record a team's mission completion time.

Request:

{
  "completionTime": 127.5
}

Get Event Dashboard

GET/api/organizer/events/{id}/dashboard

Get comprehensive event state for control center.

Response includes:

• Event details and current phase
• All teams with attendee lists
• Pending help requests
• Phase timing information

Admin Endpoints

Require admin role or higher.

Generate Audio

POST/api/admin/audio/generate

Generate TTS audio for scripts.

Request:

{
  "scripts": ["briefing-intro", "training-start"],
  "generateSegments": true
}

Create Company

POST/api/admin/companies

Create a new company.

Request:

{
  "name": "Acme Corp",
  "slug": "acme-corp",
  "ownerEmail": "owner@acme.com"
}

Content Endpoints

Get Phase Content

GET/api/events/{code}/content/{phase}

Get content segments for a phase.

Response:

{
  "success": true,
  "data": {
    "segments": [
      {
        "id": "uuid",
        "type": "intro",
        "title": "Welcome to Training",
        "audio": {
          "url": "https://...",
          "duration": 45.2,
          "pauseAfter": 3
        }
      }
    ]
  }
}

Real-Time Events

Real-time updates use Supabase Realtime channels:

Event	Channel	Payload
phase_change	`event:{code}`	newPhase, timestamp
team_complete	`event:{code}`	teamId, completionTime, rank
help_request	`organizer:{eventId}`	attendeeId, message, team
audio_play	`event:{code}`	clipId, timestamp

Subscribing

const channel = supabase
  .channel(`event:${eventCode}`)
  .on('broadcast', { event: 'phase_change' }, (payload) => {
    setCurrentPhase(payload.newPhase);
  })
  .subscribe();

// Cleanup
return () => {
  supabase.removeChannel(channel);
};

Error Codes

Status	Error	Meaning
400	INVALID_REQUEST	Missing or invalid parameters
401	UNAUTHORIZED	Not authenticated
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource doesn't exist
409	CONFLICT	State conflict (e.g., already joined)
500	SERVER_ERROR	Internal server error

Rate Limits

API endpoints have rate limits to prevent abuse:

Endpoint Type	Limit	Window
Public (event join)	10 requests	per minute
Authenticated	100 requests	per minute
Audio generation	50 requests	per hour

Next Steps

Review the Architecture for system design
Explore the Audio System
Read the Organizer Guide for practical usage