API Documentation

RESTful API for planning poker sessions, voting, and AI integration

Quick Start

Base URL

https://api.rewarders.app/api/scrumpoker

Authentication

For authenticated endpoints, include your Sanctum token in the Authorization header:

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}/stories/{story}/vote

Submit your vote on a story

Body: 
{
  "participant_id": 123,
  "value": "5"
}
Valid Values:

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

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"
  }
}
PUT /sessions/{session}

Update session details

Body: 
{
  "name": "Updated Name",
  "description": "Updated description",
  "folder_id": 2
}
POST /sessions/{session}/archive

Archive a session (soft delete)

Story Management

POST /sessions/{session}/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
}

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