Style Score API Documentation

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.

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

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.

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

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.