API Documentation - FreeScrumPoker.com

Current API Coverage

Session endpoints cover folder assignment, named-vote history, async voting, and custom card decks.

AI endpoints cover session summaries, current-story analysis, story drafting, story improvement, acceptance criteria, and story splitting.

Quick Start

Base URL

https://api.freescrumpoker.com

Authentication

For authenticated endpoints, include your Sanctum token in the Authorization header. For MCP, generate a dedicated token from the dashboard's MCP Access panel:

Authorization: Bearer YOUR_TOKEN_HERE

Response Format

All responses are JSON with this structure:

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Public Endpoints (No authentication required)

GET /sessions/{code}

Get session details by join code

Parameters:

code - 6-character session code (e.g., ABC123)

Response:

{
  "success": true,
  "session": {
    "id": "uuid",
    "name": "Sprint 42 Planning",
    "status": "active",
    "code": "ABC123",
    "participants_count": 5,
    "current_story": { ... }
  }
}

POST /sessions/{code}/join

Join a session as a guest (no account required)

Body:

{
  "name": "John Doe"
}

Response:

{
  "success": true,
  "participant": {
    "id": 123,
    "name": "John Doe",
    "role": "participant"
  },
  "session": { ... }
}

POST /sessions/{code}/vote

Submit your vote on a story

Body:

{
  "participant_id": 123,
  "vote": "5"
}

Valid Values:

0, 0.5, 1, 2, 3, 5, 8, 13, 20, 40, 100, ?, coffee

Response:

{
  "success": true,
  "vote": { ... },
  "stats": {
    "votes_cast": 3,
    "total_participants": 5,
    "all_voted": false
  }
}

GET /sessions/{code}/participants

Get list of participants in a session

Response:

{
  "success": true,
  "participants": [
    { "id": 1, "name": "Alice", "role": "moderator" },
    { "id": 2, "name": "Bob", "role": "participant" }
  ]
}

Authenticated Endpoints (Requires Sanctum token)

Session Management

GET /sessions

List all your sessions (paginated)

Query Parameters:

folder_id - Filter by folder
status - Filter by status (active/paused/completed/archived)
sort - Sort by (created_at/updated_at/name)
order - Sort direction (asc/desc)
per_page - Items per page (default: 15)

POST /sessions

Create a new planning session

Body:

{
  "name": "Sprint 42 Planning",
  "description": "Estimate authentication stories",
  "folder_id": 1  // Optional
}

Response:

{
  "success": true,
  "session": {
    "id": "uuid",
    "name": "Sprint 42 Planning",
    "code": "ABC123",  // Auto-generated
    "status": "active",
    "created_at": "2025-11-25T12:00:00Z"
  }
}

PATCH /sessions/{code}

Update session details

Body:

{
  "name": "Updated Name",
  "description": "Updated description",
  "folder_id": 2,
  "record_vote_names": true,
  "async_voting_enabled": true,
  "voting_system": "custom",
  "custom_deck_name": "Risk deck",
  "custom_deck_values": ["XS", "S", "M", "L", "XL"]
}

PATCH /sessions/{code}

Archive or unarchive a session with { "status": "archived" } or { "status": "active" }

Story Management

POST /sessions/{code}/stories

Add a new story to session

Body:

{
  "title": "User login with email/password",
  "description": "Implement basic authentication",
  "acceptance_criteria": "- Form validation\n- JWT token\n- Error handling"
}

POST /stories/{story}/reveal

Reveal votes and calculate consensus

Response:

{
  "success": true,
  "story": {
    "id": "uuid",
    "title": "User login",
    "status": "revealed",
    "final_estimate": "5",  // Consensus (mode/median)
    "votes": [
      { "participant": { "name": "Alice" }, "value": "5" },
      { "participant": { "name": "Bob" }, "value": "8" },
      { "participant": { "name": "Carol" }, "value": "5" }
    ]
  }
}

Folder Management

POST /folders

Create a folder to organize sessions

Body:

{
  "name": "Q4 2025 Sprints",
  "color": "#8b5cf6"  // Hex color code
}

AI Endpoints

Authenticated AI endpoints:

/sessions/{code}/ai/summary
/sessions/{code}/ai/analyze-current-story
/sessions/{code}/ai/draft-stories
/sessions/{code}/ai/improve-current-story
/sessions/{code}/ai/generate-acceptance-criteria
/sessions/{code}/ai/split-current-story

These endpoints are review-first tools intended to return structured suggestions for the session UI or MCP clients.

Error Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Not owner of resource
404	Not Found - Resource doesn't exist
409	Conflict - Duplicate entry
422	Validation Error - Check errors field
500	Server Error

Rate Limits

Current Limits: 60 requests per minute per IP address

Rate limit info is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000000

Integrations, Analytics, and AI Reports

Workspace and templates

Persist team defaults and reusable room templates.

GET /workspace
PATCH /workspace
POST /workspace/templates
POST /workspace/templates/{template}/sessions

Issue imports and estimate sync

Preview issues from CSV or integrations, confirm imports into a room, and queue estimate sync.

GET /integrations/providers
POST /integrations/import-preview
POST /sessions/{code}/integrations/import-confirm
POST /sessions/{code}/integrations/sync-estimates

Analytics and AI

Read estimate distribution, outliers, history, and AI estimation reports.

GET /sessions/{code}/analytics
POST /sessions/{code}/ai/estimate-assistant
POST /sessions/{code}/ai/estimation-report

Webhooks

Register custom callbacks for session and estimation events.

GET /webhooks
POST /webhooks