New leaderboard

POST /leaderboard

Headers

application/json

Body Required

  • highest_first boolean Required

    If true, higher scores/times are ranked higher, e.g. highest score is first, second highest is second.

  • is_time boolean Required

    If true, leaderboards scores are time values, e.g. 00:32

  • start string(date-time) Required

    Datetime when the leaderboard opens. Default is at time of leaderboard creation.

  • stop string(date-time)

    Datetime when the leaderboard closes. Times before the start value or empty mean the leaderboard accept submissions until the leaderboard is archived.

  • title string Required

    Leaderboard title

  • verify boolean Required

    If true, submissions need to be verified before they show up on the leaderboard.

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • $schema string(uri)

      A URL to the JSON Schema for this object.

    • id string(uuid) Required

      Unique leaderboard ID used for querying.
  • default application/problem+json

    Error

    Hide response attributes Show response attributes object
    • $schema string(uri)

      A URL to the JSON Schema for this object.

    • detail string

      A human-readable explanation specific to this occurrence of the problem.

    • errors array[object] | null

      Optional list of individual error details

      Hide errors attributes Show errors attributes object
      • location string

        Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

      • message string

        Error message text

      • value

        The value at the given location

    • instance string(uri)

      A URI reference that identifies the specific occurrence of the problem.

    • status integer(int64)

      HTTP status code

    • title string

      A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

    • type string(uri)

      A URI reference to human-readable documentation for the error.

      Default value is about:blank.
POST /leaderboard 
curl \
 --request POST 'https://api.topktoday.dev/leaderboard' \
 --header "Content-Type: application/json" \
 --header "UserID: 146b2edf-2d6f-4775-9b86-5537a2649589" \
 --data '{"highest_first":true,"is_time":false,"start":"2025-05-04T09:42:00Z","stop":"2025-05-04T09:42:00Z","title":"My First Leaderboard","verify":true}'
Request examples 
# Headers
UserID: 146b2edf-2d6f-4775-9b86-5537a2649589

# Payload
{
  "highest_first": true,
  "is_time": false,
  "start": "2025-05-04T09:42:00Z",
  "stop": "2025-05-04T09:42:00Z",
  "title": "My First Leaderboard",
  "verify": true
}
Response examples (200) 
{
  "$schema": "https://api.topktoday.dev/schemas/NewLeaderboardResponseBody.json",
  "id": "146b2edf-2d6f-4775-9b86-5537a2649589"
}
Response examples (default) 
{
  "$schema": "https://api.topktoday.dev/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}