API Documentation

Overview

Authentication

Create a new voting room. Returns the room ID, a shareable room code, and a join URL. The room expires after 72 hours of inactivity.

Rate limit: 10 requests per 15 minutes per IP

Request Body

Response

Example Response

{
  "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "roomCode": "ABC123",
  "joinUrl": "https://pointpoker.co/room/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

curl

curl -X POST https://api.pointpoker.co/api/rooms \
  -H "Content-Type: application/json" \
  -d '{
    "facilitatorName": "Sarah",
    "cardScale": "fibonacci",
    "roles": ["Dev", "QE"],
    "anonymousVoting": false
  }'

JavaScript

const response = await fetch("https://api.pointpoker.co/api/rooms", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    facilitatorName: "Sarah",
    cardScale: "fibonacci",
    roles: ["Dev", "QE"],
    anonymousVoting: false,
  }),
});
const { roomId, roomCode, joinUrl } = await response.json();

Resolve a room code to its room ID. Used when participants join via room code instead of direct link.

Rate limit: 30 requests per minute per IP

Path Parameters

Response

Example Response

{
  "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

curl

curl https://api.pointpoker.co/api/rooms/code/ABC123

JavaScript

const response = await fetch("https://api.pointpoker.co/api/rooms/code/ABC123");
const { roomId } = await response.json();

Get public metadata about a room. Used to display the join form with available roles and current participant count.

Rate limit: 30 requests per minute per IP

Path Parameters

Response

Example Response

{
  "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "roomCode": "ABC123",
  "roles": ["Dev", "QE"],
  "cardScale": "fibonacci",
  "participantCount": 4,
  "maxParticipants": 25,
  "passwordRequired": false
}

curl

curl https://api.pointpoker.co/api/rooms/a1b2c3d4-e5f6-7890-abcd-ef1234567890/info

JavaScript

const response = await fetch(
  "https://api.pointpoker.co/api/rooms/a1b2c3d4-e5f6-7890-abcd-ef1234567890/info"
);
const roomInfo = await response.json();

Health check endpoint. Returns server status, uptime in seconds, and current timestamp.

Response

Example Response

{
  "status": "ok",
  "uptime": 86400,
  "timestamp": "2026-03-08T12:00:00.000Z"
}

curl

curl https://api.pointpoker.co/health

JavaScript

const response = await fetch("https://api.pointpoker.co/health");
const { status, uptime } = await response.json();

Platform Integration API

Join a room on behalf of a platform user (Slack, Teams, Discord). Creates a participant entry and returns tokens for subsequent actions.

Auth: Bearer apiToken

Rate limit: 10 requests per minute per API token

Path Parameters

Request Body

Response

Example Response

{
  "participantId": "p_abc123",
  "participantToken": "pt_xxxxxxxxxxxxxxxx",
  "roomCode": "ABC123"
}

curl

curl -X POST https://api.pointpoker.co/api/platform/a1b2c3d4-.../join \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "name": "Sarah",
    "role": "Dev",
    "platformUserId": "U024BE7LH",
    "platform": "slack"
  }'

JavaScript

const response = await fetch(
  "https://api.pointpoker.co/api/platform/a1b2c3d4-.../join",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_API_TOKEN",
    },
    body: JSON.stringify({
      name: "Sarah",
      role: "Dev",
      platformUserId: "U024BE7LH",
      platform: "slack",
    }),
  }
);
const { participantId, participantToken } = await response.json();

Submit a vote on behalf of a platform participant. The vote value must be valid for the room's card scale.

Auth: Bearer participantToken

Rate limit: 20 requests per minute per participant token

Path Parameters

Request Body

Response

Example Response

{
  "success": true,
  "voteCount": 4,
  "totalEligible": 6
}

curl

curl -X POST https://api.pointpoker.co/api/platform/a1b2c3d4-.../vote \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PARTICIPANT_TOKEN" \
  -d '{ "value": "5" }'

JavaScript

const response = await fetch(
  "https://api.pointpoker.co/api/platform/a1b2c3d4-.../vote",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_PARTICIPANT_TOKEN",
    },
    body: JSON.stringify({ value: "5" }),
  }
);
const { success, voteCount, totalEligible } = await response.json();

Reveal all votes for the current story. Requires facilitator-level authorization.

Auth: Bearer facilitatorRestToken

Rate limit: 5 requests per minute per facilitator token

Path Parameters

Response

Example Response

{
  "votes": [
    { "participantName": "Sarah", "participantRole": "Dev", "value": "5" },
    { "participantName": "Mike", "participantRole": "QE", "value": "8" }
  ],
  "overall": { "average": 6.5, "median": 6.5, "consensus": "discuss" },
  "byRole": [
    { "role": "Dev", "count": 1, "votes": ["5"], "average": 5, "median": 5 },
    { "role": "QE", "count": 1, "votes": ["8"], "average": 8, "median": 8 }
  ]
}

curl

curl -X POST https://api.pointpoker.co/api/platform/a1b2c3d4-.../reveal \
  -H "Authorization: Bearer YOUR_FACILITATOR_TOKEN"

JavaScript

const response = await fetch(
  "https://api.pointpoker.co/api/platform/a1b2c3d4-.../reveal",
  {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_FACILITATOR_TOKEN" },
  }
);
const { votes, overall, byRole } = await response.json();

Get the current voting status of a room, including the active story, vote counts, and whether votes have been revealed.

Auth: Bearer participantToken | facilitatorRestToken

Rate limit: 30 requests per minute per token

Path Parameters

Response

Example Response

{
  "currentStory": { "id": "s_123", "title": "PP-42 Login flow", "description": null, "url": null },
  "phase": "voting",
  "voteCount": 3,
  "totalEligible": 5,
  "participantCount": 6,
  "revealResult": null
}

curl

curl https://api.pointpoker.co/api/platform/a1b2c3d4-.../status \
  -H "Authorization: Bearer YOUR_PARTICIPANT_TOKEN"

JavaScript

const response = await fetch(
  "https://api.pointpoker.co/api/platform/a1b2c3d4-.../status",
  { headers: { Authorization: "Bearer YOUR_PARTICIPANT_TOKEN" } }
);
const status = await response.json();

End the voting session and retrieve the full session history. Requires facilitator-level authorization.

Auth: Bearer facilitatorRestToken

Rate limit: 2 requests per minute per facilitator token

Path Parameters

Response

Example Response

{
  "history": [
    {
      "id": "s_123",
      "title": "PP-42 Login flow",
      "finalEstimate": "5",
      "wasRevoted": false,
      "result": { "overall": { "average": 5, "median": 5, "consensus": "consensus" } },
      "completedAt": "2026-03-20T10:30:00.000Z"
    }
  ],
  "totalStories": 1,
  "sessionDuration": 1800
}

curl

curl -X POST https://api.pointpoker.co/api/platform/a1b2c3d4-.../end-session \
  -H "Authorization: Bearer YOUR_FACILITATOR_TOKEN"

JavaScript

const response = await fetch(
  "https://api.pointpoker.co/api/platform/a1b2c3d4-.../end-session",
  {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_FACILITATOR_TOKEN" },
  }
);
const { history, totalStories, sessionDuration } = await response.json();

Deep Links

https://pointpoker.co/vote?title=PP-123%20User%20login%20flow&desc=As%20a%20user%2C%20I%20want%20to%20log%20in&url=https%3A%2F%2Fjira.example.com%2Fbrowse%2FPP-123&scale=fibonacci&timer=60&source=jira

Socket.io Events

import { io } from "socket.io-client";

const socket = io("https://api.pointpoker.co", {
  transports: ["websocket"],
});

// Join a room
socket.emit("join-room", {
  roomId: "a1b2c3d4-...",
  name: "Sarah",
  role: "Dev",
}, (response) => {
  if (response.success) {
    console.log("Joined!", response.state);
  } else {
    console.error(response.error);
  }
});

{
  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)
}

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

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

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

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

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

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

{ participantId: string }

{
  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;
}

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

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

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

{ message: string }

Rate Limits

Card Scales

Error Handling

{
  "error": "Human-readable error message"
}