API Documentation

Join a voting room. Returns full room state on success.

{
  roomId: string;       // Room ID to join
  name: string;         // Your display name
  role: string;         // Your role (must be in room's role list)
  asObserver?: boolean;  // Join as non-voting observer
  reconnectToken?: string; // Token for reconnecting after disconnect
  avatarSeed?: string;   // Seed for avatar generation
  password?: string;     // Room password (if required)
}

Returns a callback with { success, state, participantId, reconnectToken } or { success: false, error }.

Submit or change your vote for the current story.

{ value: string }  // Must be a valid card value for the room's scale

If autoReveal is enabled and all eligible voters have voted, votes are automatically revealed.

Clear your current vote.

Set the current story for voting. Clears all votes and starts a new round.

{
  title: string;        // Story title (required)
  description?: string; // Story description (max 1000 chars)
  url?: string;         // Link to ticket (max 500 chars)
}

Reveal all votes and compute statistics (average, median, consensus).

When the "open controls" feature is enabled, any non-observer participant can reveal.

Move to the next story. Archives the current story to session history.

Clear all votes and restart voting on the current story.

Add a story to the voting queue.

{
  title: string;        // Story title (1-200 chars)
  description?: string; // Description (max 1000 chars)
  url?: string;         // Ticket URL (max 500 chars)
}

Add multiple stories to the queue at once.

{ titles: string[] }  // Array of story titles (max 50 items)

Start voting on the next story in the queue.

Remove (kick) a participant from the room.

{ participantId: string }  // ID of participant to remove

Transfer facilitator role to another participant.

{ targetParticipantId: string }

Remove a story from the queue.

{ storyId: string }

Reorder stories in the queue by providing the new order.

{ orderedIds: string[] }  // Story IDs in desired order

Update the title, description, or URL of a queued story.

{
  storyId: string;
  title: string;
  description?: string;
  url?: string;
}

Skip the current story mid-vote and return it to the front of the queue. Clears all votes.

Requires the skip-story feature flag. The skipped story goes back to the top of the queue so it can be revisited later.

Start voting on a specific story from the queue (not necessarily the next one).

{ storyId: string }  // ID of the queued story to start

The current story (if revealed) is archived to history before the new story starts.

Switch an observer to a voting participant. Facilitators can switch any observer; non-facilitators can only switch themselves.

{
  participantId: string;  // ID of the observer to switch
  role?: string;          // Role to assign (must be in room's role list)
}

Requires the observer-switch feature flag. The facilitator cannot be switched (they are never an observer).

Override the final estimate for the current story after votes are revealed.

{ value: string }  // The final agreed-upon estimate

Update room settings mid-session (timer, auto-reveal, facilitator participation, etc.).

{
  votingTimerSeconds?: number | null;
  autoReveal?: boolean;
  facilitatorParticipates?: boolean;
  anonymousVoting?: boolean;
}

Extend the voting timer by the room's configured timer duration.

Only works when a timer is active and has expired or is about to expire.

Send an emoji reaction visible to all participants. Used for quick team mood feedback.

{ emoji: string }  // A single emoji character

Any participant (including observers) can react. Rate limited to 5 per 10 seconds.

Update your own participant data (e.g., display name).

{ name?: string }

Mark the session as done for today. Broadcasts the current history to all participants and shows a session summary screen. The room stays alive — participants can resume later.

Idempotent — calling it when already done is a no-op. The room TTL is not reset by this event; use resume-from-done to continue the session.

Resume a session that was marked as done for today, returning all participants to the active room view.

Idempotent — calling it when the session is not in a done state is a no-op.

End the voting session. Broadcasts session history to all participants and closes the room.

Full room state broadcast. Sent on join and after major state changes.

{
  config: RoomConfig;
  participants: Participant[];
  currentStory: Story | null;
  votingStatus: Record<string, boolean>;
  revealResult: RevealResult | null;
  history: CompletedStory[];
  storyQueue: QueuedStory[];
  finalEstimateOverride: string | null;
}

A new participant joined the room.

{
  id: string;
  name: string;
  role: string;
  isFacilitator: boolean;
  isObserver: boolean;
  connectionStatus: "online" | "offline";
  hasVoted: boolean;
}

A participant disconnected from the room.

{ participantId: string }

A participant's connection status changed (online/offline).

{
  participantId: string;
  status: "online" | "offline";
}

A participant was removed (kicked) from the room by the facilitator.

{ participantId: string }

A participant submitted or changed their vote (value is hidden until reveal).

{ participantId: string }

A participant cleared their vote.

{ participantId: string }

Votes have been revealed. Includes per-vote data, averages, and consensus status.

{
  votes: Array<{
    participantId: string;
    participantName: string;
    participantRole: string;
    value: string;
  }>;
  overall: {
    average: number | null;
    median: number | null;
    consensus: "consensus" | "discuss";
  };
  byRole: Array<{
    role: string;
    count: number;
    votes: string[];
    average: number | null;
    median: number | null;
  }>;
  hasRoleGap: boolean;
}

Voting was reset (revote). All votes are cleared and a new timer starts if configured.

{ timerEndsAt: string | null }

The current story has changed.

{
  id: string;
  title: string;
  description: string | null;
  url: string | null;
  phase: "waiting" | "voting" | "revealed";
  timerEndsAt: string | null;
}

The current story was skipped and returned to the queue.

{
  queue: Array<{
    id: string;
    title: string;
    description: string | null;
    url: string | null;
  }>
}

The story queue has been modified (added, removed, or reordered).

{
  queue: Array<{
    id: string;
    title: string;
    description: string | null;
    url: string | null;
  }>
}

The facilitator role was transferred to a different participant.

{ newFacilitatorId: string }

The facilitator set or changed the final estimate override for the current story.

{ value: string | null }

The voting timer has expired.

The voting timer is about to expire. Shows current vote progress for the extend/reveal prompt.

{
  votedCount: number;
  totalCount: number;
}

The voting timer was extended by the facilitator.

{ timerEndsAt: string }  // ISO 8601 timestamp

A participant sent an emoji reaction.

{
  participantId: string;
  participantName: string;
  emoji: string;
}

The facilitator marked the session as done for today. All participants switch to the session summary screen.

{
  history: Array<{
    id: string;
    title: string;
    finalEstimate: string | null;
    wasRevoted: boolean;
    result: RevealResult;
    completedAt: string;
  }>
}

The facilitator resumed a session that was done for today. All participants return to the active room view.

The session has ended. Includes full voting history for all stories.

{
  history: Array<{
    id: string;
    title: string;
    finalEstimate: string | null;
    wasRevoted: boolean;
    result: RevealResult;
    completedAt: string;
  }>
}

Server is forcing a disconnect (e.g., participant was kicked or room was closed).

{ reason: string }

An error occurred processing your request.

{ message: string }