# Style Score API Documentation

Complete reference for all API endpoints with interactive testing capabilities

##### API Overview

The Style Score API provides programmatic access to competition data, results, and administrative functions. All endpoints return JSON responses with UTF-8 encoding for proper international character support.

###### Base URL

http://localhost/v2/api/

###### Test Event ID

Default for testing

##### Audience & Capabilities

This documentation is organized by role so you can quickly find the APIs relevant to your job.

###### For Admins / Event Managers

- Heat Management API — control active heats/runs, participant queues, and quick actions (activate/deactivate, mark started/completed).
- User Management API — manage users, status, and bulk operations.
- Token Management API — inspect/create budgets and export transactions.
- Result Configurations API — save and apply display templates and export formats.

###### For Judges & Head Judges

- Judge Scoring API — submit and update scores (figure-level data supported).
- Head Judge API — review and approve scores, create or adjust individual scores, and bulk approval actions.
- Diversity Rules API — validate figure selections and rule compliance before submitting scores.

###### For Public / Display

- Public Dashboard API — read-only feeds for live displays and public scoreboards.
- Summary Table API — ready-made scoring tables for publishing or CSV export.
- Start List API — printable start lists and lane assignments.

###### For Developers / Integrations

- Notification API — push and poll notifications for UI updates and external systems.
- Heat Flow API — programmatic access to heat/flow definitions and live state for automation.
- Categories & Result Configurations APIs — metadata endpoints useful for building client-side UI and export tooling.

Security notes: Many endpoints (Judge, Head Judge, Heat Management, User/Token management) require an authenticated session and appropriate role (judge, head_judge, admin). Public endpoints are read-only and safe for embedding. Always test POST calls against a non-production event when possible.

##### Summary Table API

GET

Generates scoring summary tables with flexible filtering options and multiple output formats.

###### Endpoint

/api/summary_table_api.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`event_id` | integer | Yes | Event identifier
`category` | string | No | Category filter (default: "all")
`heat_run_filter` | JSON | No | Heat and run filtering: {"heat_id":[run1,run2]}
`format` | string | No | Output format: json, html, csv, pdf
`config_id` | integer | No | Saved configuration ID
`action` | string | No | Special actions: 'promote', 'get_participants_to_promote'

###### Test Examples

##### Start List API

GET

Generates official start lists for events and heats with multiple output formats.

###### Endpoint

/api/start_list_api.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`event_id` | integer | Yes | Event identifier
`heat_number` | integer | No | Specific heat number (omit for all heats)
`format` | string | No | Output format: json, html, csv, pdf
`page` | integer | No | Page number for pagination
`limit` | integer | No | Items per page (default: 50)

###### Test Examples

##### Categories API

GET

Returns distinct participant categories for a given event.

###### Endpoint

/api/get_categories.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`event_id` | integer | Yes | Event identifier

###### Test Example

##### Public Dashboard API

GET

Provides data for public dashboards and live displays.

###### Endpoint

/api/public_dashboard_api.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`action` | string | Yes | Action to perform (varies by endpoint)
`event_id` | integer | Conditional | Event ID for event-specific data

###### Test Example

##### Notification API

GET/POST

Real-time notification system for competition events with CORS support.

###### Endpoint

/api/notification_api.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`action` | string | No | Notification action type
`event_id` | integer | No | Event ID for event-specific notifications

###### Test Example

##### Result Configurations API

GET/POST

Manages saved configurations for start lists and summary tables.

###### Endpoint

/api/result_configurations_api.php

###### Actions

Action | Method | Description
--- | --- | ---
`list` | GET | List all configurations
`get` | GET | Get specific configuration
`save` | POST | Save new configuration
`delete` | POST | Delete configuration

###### Test Example

##### Heat Flow API

GET

Provides comprehensive heat flow chains, live progress, participant tracking, and real-time results integration.

###### Endpoint

/admin/heat_flow_api.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`event_id` | integer | Yes | Event identifier

###### Test Example

##### Heat Management API

GET/POST

Manages heat settings, participant queues, and real-time heat operations.

###### Endpoint

/admin/heat_management_api.php

###### Available Actions

Action | Method | Parameters | Description
--- | --- | --- | ---
`get_data` | GET | event_id | Get heat management data
`update_settings` | POST | event_id, active_heat, active_run, bib_on_start | Update heat settings
`get_participants` | GET | event_id, heat_number | Get heat participants
`get_queue` | GET | event_id, heat_number, mode | Get participant queue
`update_participant_status` | POST | event_id, bib_number, status | Update participant status
`deactivate_all` | POST | event_id | Deactivate all heats

###### Test Example

##### Judge Scoring API

POST

Submit and manage judge scores with figure selection and diversity validation.

###### Endpoint

/judge/score.php

###### Score Submission Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`ajax` | string | Yes | Set to '1' for AJAX requests
`ep_id` | integer | Yes | Event participant ID
`heat_number` | integer | Yes | Heat number
`score_value` | float | No | Score value (null for no score)
`status` | string | Yes | Score status: 'scored', 'no_score', 'dns', 'dnf'
`figures_json` | JSON | No | Selected figures data

Note: Judge scoring requires authenticated session. Use browser credentials when testing.

##### Head Judge API

POST

Head judge operations for score management, approval, and oversight.

###### Endpoint

/judge/head_judge.php

###### Available Actions

Action | Parameters | Description
--- | --- | ---
`get_scores` | ajax=1, action, event_id, heat_number, run_number | Get scores for review
`update_score` | ajax=1, action, score_id, score_value, status | Update existing score
`create_score` | ajax=1, action, ep_id, judge_id, score_value | Create new score
`approve_score` | ajax=1, action, score_id | Approve a score
`approve_all_participant` | ajax=1, action, participant_id | Approve all scores for participant

Authorization Required: Head judge or admin role required.

##### Diversity Rules API

GET

Validates diversity rule compliance for participant scores and figure selections.

###### Endpoint

/api/check_diversity_rules.php

###### Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`ep_id` | integer | Yes | Event participant ID
`judge_id` | integer | Yes | Judge ID
`event_id` | integer | Yes | Event ID
`heat_number` | integer | No | Heat number

###### Test Example

##### User Management API

GET/POST

Comprehensive user management operations for administrators.

###### Endpoint

/admin/api/user_management_api.php

###### Available Actions

Action | Method | Parameters | Description
--- | --- | --- | ---
`get_user` | GET | action, id | Get user details
`search_users` | GET | action, q | Search users
`update_user_status` | POST | action, user_id, status | Update user status
`bulk_action` | POST | action, user_ids[], bulk_action | Bulk operations (activate/deactivate/delete)

Admin Only: Requires super_admin or admin role.

##### Token Management API

GET/POST

Token system management for budget and transaction operations.

###### Endpoint

/admin/api/token_management_api.php

###### Available Actions

Action | Method | Parameters | Description
--- | --- | --- | ---
`get_user_budget` | GET | action, user_id | Get user budget information
`get_transactions` | GET | action, user_id | Get user transactions
`create_budget` | POST | action, user_id | Create budget for user
`export_transactions` | GET | action, user_id | Export user transactions as CSV
`export_all_*` | GET | action | Various export options for system data

Admin Access: Requires super_admin or admin permissions.

##### Response Schemas & POST Examples

Representative JSON responses, HTTP response codes, and concrete POST examples (fetch + cURL) for the most-used endpoints. These are samples — fields may vary by configuration. Use the interactive test buttons above to get live data for `event_id` = 3.

###### Common HTTP responses

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

    // Error examples
    { "success": false, "message": "Missing parameter: event_id" }  // 400 Bad Request
    { "success": false, "message": "Unauthorized" }                // 401 Unauthorized
    { "success": false, "message": "Forbidden" }                   // 403 Forbidden
    { "success": false, "message": "Internal server error" }      // 500 Server Error

###### Summary Table API (GET) — Example Response

    {
        "event_id": 3,
        "format": "standard",
        "participants": [
            {
                "ep_id": 101,
                "bib_number": 12,
                "name": "Jane Doe",
                "category": "Senior",
                "heat": 1,
                "run": 1,
                "scores": {
                    "total": 27.5,
                    "details": [
                        { "judge_id": 5, "value": 9.0 },
                        { "judge_id": 6, "value": 9.5 },
                        { "judge_id": 7, "value": 9.0 }
                    ]
                },
                "place": 1,
                "promotion": "auto"
            }
        ]
    }

###### Start List API (GET) — Example Response

    {
        "event_id":3,
        "heats":[
            {"heat_number":1,"participants":[{"bib":12,"name":"Jane Doe","lane":3}]}
        ]
    }

###### Heat Flow API (GET) — Example Response

    {
        "event_id":3,
        "flows":[
            {"flow_id":1,"name":"Prelims","heats":[{"heat_number":1,"runs":[1,2]}]},
            {"flow_id":2,"name":"Finals","heats":[{"heat_number":5,"runs":[1]}]}
        ],
        "live": {"active_heat":5,"active_run":1,"started_at":"2025-08-21T10:12:00Z"}
    }

###### Heat Management API — POST examples (fetch + cURL)

Endpoint: `/admin/heat_management_api.php`. Use `action` to select behavior. Many admin endpoints require an authenticated admin session.

update_settings (fetch)

    const fd = new FormData();
    fd.append('action','update_settings');
    fd.append('event_id', 3);
    fd.append('active_heat', 5);
    fd.append('active_run', 1);
    fd.append('bib_on_start', 1);

    fetch('/v2/admin/heat_management_api.php', { method: 'POST', body: fd, credentials: 'include' })
      .then(r => r.json())
      .then(data => console.log(data));

update_settings (cURL)

    curl -X POST \
      -F "action=update_settings" \
      -F "event_id=3" \
      -F "active_heat=5" \
      -F "active_run=1" \
      -F "bib_on_start=1" \
      --cookie "PHPSESSID=YOUR_SESSION" \
      http://localhost/v2/admin/heat_management_api.php

update_participant_status (POST)

    {
      "action":"update_participant_status",
      "event_id":3,
      "bib_number":12,
      "status":"on_deck"   /* values: on_deck, started, finished, dns, dnf */
    }

deactivate_all (POST)

    curl -X POST -F "action=deactivate_all" -F "event_id=3" --cookie "PHPSESSID=YOUR_SESSION" http://localhost/v2/admin/heat_management_api.php

###### Judge Scoring API (POST) — How to send a score (examples)

Endpoint: `/judge/score.php`. Use `ajax=1` for AJAX handlers. Score submissions require an authenticated judge session.

Minimal score POST (fetch, form-encoded)

    const form = new URLSearchParams();
    form.append('ajax', 1);
    form.append('ep_id', 101);
    form.append('heat_number', 1);
    form.append('score_value', 9.5);
    form.append('status', 'scored');
    form.append('figures_json', JSON.stringify({ figures:[{id:1,value:9.5}] }));

    fetch('/v2/judge/score.php', { method: 'POST', body: form, credentials: 'include' })
      .then(r => r.json())
      .then(data => console.log(data));

Overwrite score (AJAX) — fetch example

    const fd = new FormData();
    fd.append('ajax',1);
    fd.append('overwrite_score_id', 999);
    fd.append('score_value', 9.8);

    fetch('/v2/judge/score.php', { method:'POST', body: fd, credentials:'include' })
      .then(r=>r.json()).then(console.log);

Minimal score POST (cURL, form)

    curl -X POST \
      -d "ajax=1" \
      -d "ep_id=101" \
      -d "heat_number=1" \
      -d "score_value=9.5" \
      -d "status=scored" \
      -d "figures_json={\"figures\":[{\"id\":1,\"value\":9.5}]}" \
      --cookie "PHPSESSID=YOUR_SESSION" \
      http://localhost/v2/judge/score.php

Score endpoints require an authenticated judge session. For interactive testing use the browser where you're logged in or use a valid session cookie in cURL. Avoid running POST tests on live events without permission.

###### Head Judge API (POST) — Actions & examples

Endpoint: `/judge/head_judge.php`. Use `ajax=1` and `action` parameter. Head Judge endpoints require head_judge or admin role.

get_scores (fetch)

    fetch('/v2/judge/head_judge.php', {
      method: 'POST',
      body: new URLSearchParams({ ajax:1, action: 'get_scores', event_id:3, heat_number:1 }),
      credentials: 'include'
    }).then(r=>r.json()).then(console.log);

update_score (cURL JSON)

    curl -X POST http://localhost/v2/judge/head_judge.php \
      -H "Content-Type: application/json" \
      --data '{"ajax":1,"action":"update_score","score_id":555,"score_value":9.2,"status":"scored"}' \
      --cookie "PHPSESSID=YOUR_SESSION"

approve_all_participant (fetch)

    fetch('/v2/judge/head_judge.php', {
      method:'POST',
      body: new URLSearchParams({ ajax:1, action:'approve_all_participant', participant_id:101 }),
      credentials:'include'
    }).then(r=>r.json()).then(console.log);

###### Diversity Rules API (GET) — Example Response

    {
        "ep_id":101,
        "violations":[],
        "valid":true,
        "message":"OK"
    }

###### User Management & Token Management — Examples

    /* User search (GET) */
    { "users": [{"id":12,"username":"jdoe","role":"judge","status":"active"}] }

    /* Token get_user_budget (GET) */
    { "user_id":12, "budget":150, "currency":"tokens" }

    /* Token create_budget (POST) example */
    { "action":"create_budget", "user_id":12, "amount":100 }

###### Notification API — Example (GET)

    {
        "notifications":[ {"id":1,"event_id":3,"title":"Heat started","body":"Heat 5 run 1 has started","level":"info"} ]
    }

###### Public Dashboard — Typical usage

    // Dashboard data (GET)
    fetch('/v2/api/public_dashboard_api.php?action=event_summary&event_id=3')
      .then(r=>r.json()).then(console.log);

Want cURL snippets added as clickable buttons or a separate "try POST" area? I can add them, but note POST endpoints require authentication and may modify live events — I will add warnings and an optional demo mode if you want.

##### Usage Examples

##

    // Fetch summary table data
    fetch('/v2/api/summary_table_api.php?event_id=3&category=all')
      .then(response => response.json())
      .then(data => {
        console.log('Summary data:', data);
        // Process the results
      })
      .catch(error => console.error('Error:', error));

    // Get start list for specific heat
    fetch('/v2/api/start_list_api.php?event_id=3&heat_number=1')
      .then(response => response.json())
      .then(data => {
        console.log('Start list:', data);
      });

##

     'list']));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
    ?>

##

    # Get summary table data
    $response = Invoke-RestMethod -Uri "http://localhost/v2/api/summary_table_api.php?event_id=3"
    $response | ConvertTo-Json -Depth 10

    # Get start list with specific parameters
    $uri = "http://localhost/v2/api/start_list_api.php?event_id=3&heat_number=1&format=json"
    $startList = Invoke-RestMethod -Uri $uri
    Write-Host "Retrieved $($startList.count) participants"

    # Download CSV format
    Invoke-WebRequest -Uri "http://localhost/v2/api/summary_table_api.php?event_id=3&format=csv" -OutFile "results.csv"

##### Error Handling & Best Practices

###### Common Error Responses

- `{"success": false, "message": "No event ID provided"}`
- `{"success": false, "message": "Event not found"}`
- `{"success": false, "message": "Database connection failed"}`
- `{"success": false, "message": "Invalid action"}`

###### Best Practices

- Always check the `success` field in responses
- Handle network errors and timeouts gracefully
- Use appropriate HTTP status codes in your applications
- Implement proper error logging and monitoring
- Cache responses when appropriate to reduce server load