Pelican (1.0.0)

Download OpenAPI specification:

Pelican users api

session

POST user register

Register the user in with an email and password

Request Body schema: application/json
required

Registration data

email	string
name	string free text user name
password	string the password
c_password	string a repeat of the password

Responses

Request samples

Payload

Content type

application/json

{"email": "spmcquizz@example.ca",
"name": "Seanathan P. McQuizz",
"password": "<redacted>",
"c_password": "<redacted>"
}

Response samples

201
404

Content type

application/json

{"data": {"token": "<redacted>",
"name": "Seanathan P. McQuizz",
"email": "spmcquizz@example.ca",
"uuid": "67d3084426bb0"
}
}

POST user login

Log the user in with an email and password

Request Body schema: application/json
required

Login data

email	string
password	string

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.ca",
"password": "<redacted>"
}

Response samples

201
404

Content type

application/json

{"data": {"token": "<redacted>",
"name": "Seanathan P. McQuizz",
"email": "spmcquizz@example.ca",
"uuid": "67d3084426bb0"
}
}

GET Google oauth url

Gets the url for redirecting for google oauth authorization.

Logging in via oauth is a three step process:

Get the oauth url: Call this endpoint, get value of url
Redirect to that url: Redirect the user's browser to url
Call the authenticate endpoint: The user's browser will be redirect again back to the front end with a code value in the query string. Call the authenticate endpoint with code on the query string.

This process will log the user in.

Important
For development and staging, only approved Google accounts can log in. All others will fail with a 401.
Approved Google accounts are:

Responses

Response samples

200
401
404

Content type

application/json

{"data": {"url": "https://accounts.google.com/o/oauth2/auth?client_id=292802987542-2a6lostncjob6p8vm4pom2vbd8l6frdk.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fstaging.pelicantrivia.info%2Fcallback.php&scope=openid+profile+email&response_type=code"
}
}

POST Google authenticate

Post the code from Google to log the user in.

Logging in via oauth is a three step process:

Get the oauth url: Call this endpoint, get value of url
Redirect to that url: Redirect the user's browser to url
Call the authenticate endpoint: The user's browser will be redirect again back to the front end with a code value in the query string. Call the authenticate endpoint with code on the query string.

This process will log the user in.

Important
For development and staging, only approved Google accounts can log in. All others will fail with a 401.
Approved Google accounts are:

Responses

Response samples

201
401
404

Content type

application/json

{"data": {"token": "<redacted>",
"name": "Seanathan P. McQuizz",
"email": "spmcquizz@example.ca",
"uuid": "67d3084426bb0"
}
}

users

GET me

Get details on the current session user

Responses

Response samples

200
404

Content type

application/json

{"data": {"uuid": "67c8746bc1256",
"name": "Seanathan P. McQuizz",
"email": "spmcq@example.ca",
"elo": 1200,
"current_streak": 4,
"longest_streak": 23,
"avatar": "https://example.ca/me.png",
"role": {"id": 2,
"name": "Normal User",
"description": "Normal User"
},
"football": {"current_yardline": 40,
"total_yards": 900,
"total_complete": 12
},
"badges": [{"name": "First Question Correct",
"description": "First Question Correct",
"image": "https://example.ca/img/firstquestioncorrect.png"
}
]
}
}

GET my stats

Get play stats for the session user for the 'general' game.

Responses

Response samples

200
500

Content type

application/json

{"data": {"start_date": "2025-03-01 12:34:56",
"end_date": "2025-03-01 12:34:56",
"total_responses": 18,
"total_responses_correct": 9,
"highest_user_elo": 1410,
"lowest_user_elo": 980,
"current_user_elo": 1280,
"highest_correct_elo": 1740,
"current_streak": 4,
"longest_streak": 8,
"ratio": 50
}
}

questions

GET one question

Returns one question and it's associated HATEOAS links by its id.

Any question can be in one of two formats: 'text' or 'img'.

'text' questions are simple written questions, ie 'What province is Saskatchewan'
'img' questions display an image with a caption, ie an outline of Saskatchewan with the caption 'what province is this?'

Options are the potentials responses to a question, identified by a uuid. They also can be in one of two formats: 'text' or 'img'.

To quickly determine if an option is correct for the question, the returned hash can be tested. The hashing formula is md5(salt+option_id) where the salt is the pre-determined value. For implementations where 'cheating' is of consequence, the hash functionality may be removed.

operationId: getQuestion

path Parameters

id

required

integer >= 1

The id of the question

Responses

Response samples

200
404

Content type

application/json

{"data": {"id": 100,
"text": "What is Saskatchewan?",
"image_url": "string",
"caption": "string",
"source": "string",
"format": "text",
"elo": 1000,
"rating": "Easy",
"hash": "string",
"options": [{"id": "f504712b-e173-4af6-86f9-58b4993392b0",
"text": "Saskatchewan",
"image_url": "http://foo.dev/saskatchewan.png",
"caption": "A square",
"format": "text",
"links": {"basic": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
},
"timeout": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
}
}
}
],
"tags": [{"id": 6,
"name": "Sports"
}
]
}
}

GET question set by tag

Returns a set of questions for a given tag id.

The number of questions in the set is determined by count passed on the query string.

if count is less than 10, 10 is used
if count is greater than 50, 50 is used

Any question can be in one of two formats: 'text' or 'img'.

'text' questions are simple written questions, ie 'What province is Saskatchewan'
'img' questions display an image with a caption, ie an outline of Saskatchewan with the caption 'what province is this?'

Options are the potentials responses to a question, identified by a uuid. They also can be in one of two formats: 'text' or 'img'.

To quickly determine if an option is correct for the question, the returned hash can be tested. The hashing formula is md5(salt+option_id) where the salt is the pre-determined value. For implementations where 'cheating' is of consequence, the hash functionality may be removed.

operationId: getSetByTag

path Parameters

count required	integer [ 1 .. 50 ] Example: 2 The count of questions
id required	integer >= 1 Example: 2 The id of the tag

Responses

Response samples

200
404

Content type

application/json

{"data": [{"id": 100,
"text": "What is Saskatchewan?",
"image_url": "string",
"caption": "string",
"source": "string",
"format": "text",
"elo": 1000,
"rating": "Easy",
"hash": "string",
"options": [{"id": "f504712b-e173-4af6-86f9-58b4993392b0",
"text": "Saskatchewan",
"image_url": "http://foo.dev/saskatchewan.png",
"caption": "A square",
"format": "text",
"links": {"basic": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
},
"timeout": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
}
}
}
],
"tags": [{"id": 6,
"name": "Sports"
}
]
}
]
}

GET question set by tag set

Returns a set of questions by a list of tags.

The tag list is a csv string of tag ids, ie '3,9,12'. The number of questions to return is the count.

The count of questions requested must be at least three times larger than the number of tags in the tag list. ie. if the tags requested are '2,17,5' (three tags in total), then the count of questions must be at least 9.

The number of questions from each tag is proportionally balanced. For example, if the tags requested are '2,7' and tag 2 has 800 questions and tag 7 has 200 questions, then the question set returned will have four times as many questions from tag 2 as from tag 7. This prevents questions from tags that have smaller number of total questions from being overweighted.

if count is less than 10, 10 is used
if count is greater than 50, 50 is used

Any question can be in one of two formats: 'text' or 'img'.

'text' questions are simple written questions, ie 'What province is Saskatchewan'
'img' questions display an image with a caption, ie an outline of Saskatchewan with the caption 'what province is this?'

Options are the potentials responses to a question, identified by a uuid. They also can be in one of two formats: 'text' or 'img'.

To quickly determine if an option is correct for the question, the returned hash can be tested. The hashing formula is md5(salt+option_id) where the salt is the pre-determined value. For implementations where 'cheating' is of consequence, the hash functionality may be removed.

operationId: getSetByTag

path Parameters

count required	integer [ 1 .. 50 ] Example: 10 The count of questions
ids required	string Example: 2,15,7 The id string of the tags

Responses

Response samples

200
404

Content type

application/json

{"data": [{"id": 100,
"text": "What is Saskatchewan?",
"image_url": "string",
"caption": "string",
"source": "string",
"format": "text",
"elo": 1000,
"rating": "Easy",
"hash": "string",
"options": [{"id": "f504712b-e173-4af6-86f9-58b4993392b0",
"text": "Saskatchewan",
"image_url": "http://foo.dev/saskatchewan.png",
"caption": "A square",
"format": "text",
"links": {"basic": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
},
"timeout": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
}
}
}
],
"tags": [{"id": 6,
"name": "Sports"
}
]
}
]
}

POST basic response

Submits one basic resonse to a question.

path Parameters

id required	integer >= 1 The id of the questions
uuid required	string The uuid of the option

Responses

Response samples

201
500

Content type

application/json

{"data": {"is_correct": true,
"additional_facts": "Some optional facts about the trivia",
"stats": {"correct": 9,
"incorrect": 3,
"percentage_correct": 75
}
}
}

POST timeout response

Submits one timeout resonse to a question.

path Parameters

id

required

integer >= 1

The id of the questions

Responses

Response samples

201
500

Content type

application/json

{"data": {"is_correct": true,
"additional_facts": "Some optional facts about the trivia",
"stats": {"correct": 9,
"incorrect": 3,
"percentage_correct": 75
}
}
}

football

GET question set for football game

Returns a set of questions from 'football' tags (103 and 105)

if count is less than 10, 10 is used
if count is greater than 50, 50 is used

Any question can be in one of two formats: 'text' or 'img'.

'text' questions are simple written questions, ie 'What province is Saskatchewan'
'img' questions display an image with a caption, ie an outline of Saskatchewan with the caption 'what province is this?'

Options are the potentials responses to a question, identified by a uuid. They also can be in one of two formats: 'text' or 'img'.

To quickly determine if an option is correct for the question, the returned hash can be tested. The hashing formula is md5(salt+option_id) where the salt is the pre-determined value. For implementations where 'cheating' is of consequence, the hash functionality may be removed.

operationId: getQuestionsFootball

path Parameters

count

required

integer [ 1 .. 50 ]

Example: 10

The count of questions

Responses

Response samples

200
404

Content type

application/json

{"data": [{"id": 100,
"text": "What is Saskatchewan?",
"image_url": "string",
"caption": "string",
"source": "string",
"format": "text",
"elo": 1000,
"rating": "Easy",
"hash": "string",
"options": [{"id": "f504712b-e173-4af6-86f9-58b4993392b0",
"text": "Saskatchewan",
"image_url": "http://foo.dev/saskatchewan.png",
"caption": "A square",
"format": "text",
"links": {"basic": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
},
"timeout": {"href": "https://api.pelicantrivia.info/some/endpoint",
"type": "GET"
}
}
}
],
"tags": [{"id": 6,
"name": "Sports"
}
]
}
]
}

POST basic response for football

Submits one basic resonse to a question for the football game.

Behaves the same as POST /api/questions/{id}/options/{uuid}/basic with the exception that football stats are logged for building football-sepcific leaderboards and badge awards

path Parameters

id required	integer >= 1 The id of the questions
uuid required	string The uuid of the option

Responses

Response samples

201
500

Content type

application/json

{"data": {"is_correct": true,
"additional_facts": "Some optional facts about the trivia",
"stats": {"correct": 9,
"incorrect": 3,
"percentage_correct": 75
}
}
}

GET total leaderboard

Returns a leaderboard of the total questions responded to.

The leaderboard is the top count users who, over the last days have responded to the most total questions, both correctly and incorrectly.

operationId: getLeaderboardTotal

`path Parameters`

count required	integer [ 1 .. 25 ] Example: 10 The number of distinct users to return
days required	integer [ 1 .. 30 ] Example: 7 The number of days back from now to sample

`Responses`


/api/football/leaderboard/total/top/{count}/days/{days}

`Response samples`

200
500

Content typeapplication/json

{"data": [{"name": "Seanathan P. McQuizz",
"avatar": "https://example.ca/avatar.png",
"stat": 70
}
]
}

`GET correct leaderboard`

Returns a leaderboard of the total questions responded to correctly.

The leaderboard is the top count users who, over the last days have responded to the most total questions correctly

operationId: getLeaderboardCorrect

`path Parameters`

count required	integer [ 1 .. 25 ] Example: 10 The number of distinct users to return
days required	integer [ 1 .. 30 ] Example: 7 The number of days back from now to sample

`Responses`


/api/football/leaderboard/correct/top/{count}/days/{days}

`Response samples`

200
500

Content typeapplication/json

{"data": [{"name": "Seanathan P. McQuizz",
"avatar": "https://example.ca/avatar.png",
"stat": 70
}
]
}

`GET ratio leaderboard`

Returns a leaderboard of the highest correct ratios

The leaderboard is the top count users by the ratio of correct answers over the last days days.

Users must have responded to, on average, a minimum of two questions per day to be included in the leaderboard.

operationId: getLeaderboardRatio

`path Parameters`

count required	integer [ 1 .. 25 ] Example: 10 The number of distinct users to return
days required	integer [ 1 .. 30 ] Example: 7 The number of days back from now to sample

`Responses`


/api/football/leaderboard/ratio/top/{count}/days/{days}

`Response samples`

200
500

Content typeapplication/json

{"data": [{"name": "Seanathan P. McQuizz",
"avatar": "https://example.ca/avatar.png",
"stat": 70
}
]
}

`PUT yardline`

Registers the current yardline of the session user.

`path Parameters`

yl

required

integer [ 0 .. 100 ]

The yardline of the user

`Responses`


/api/users/me/football/yardline/{yl}

`Response samples`

201
500

Content typeapplication/json

{"data": {"current_yardline": 40,
"total_yards": 240,
"total_complete": 2
}
}

`PUT complete`

Increments the count of complete football games for the session user.

`Responses`


/api/users/me/football/complete

`Response samples`

201
500

Content typeapplication/json

{"data": {"current_yardline": 40,
"total_yards": 240,
"total_complete": 2
}
}

`GET my football stats`

Get play stats for the session user for the 'football' game.

`Responses`


/api/users/me/stats/football

`Response samples`

200
500

Content typeapplication/json

{"data": {"start_date": "2025-03-01 12:34:56",
"end_date": "2025-03-01 12:34:56",
"total_responses": 18,
"total_responses_correct": 9,
"highest_user_elo": 1410,
"lowest_user_elo": 980,
"current_user_elo": 1280,
"highest_correct_elo": 1740,
"current_streak": 4,
"longest_streak": 8,
"total_yards": 350,
"total_complete": 3,
"ratio": 50
}
}

Pelican (1.0.0)

session

POST user register

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

POST user login

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

GET Google oauth url

Responses

Response samples

POST Google authenticate

Responses

Response samples

users

GET me

Responses

Response samples

GET my stats

Responses

Response samples

questions

GET one question

path Parameters

Responses

Response samples

GET question set by tag

path Parameters

Responses

Response samples

GET question set by tag set

path Parameters

Responses

Response samples

POST basic response

path Parameters

Responses

Response samples

POST timeout response

path Parameters

Responses

Response samples

football

GET question set for football game

path Parameters

Responses

Response samples

POST basic response for football

path Parameters

Responses

Response samples

GET total leaderboard

path Parameters

Responses

Response samples

GET correct leaderboard

path Parameters

Responses

Response samples

GET ratio leaderboard

path Parameters

Responses

Response samples

PUT yardline

path Parameters

Responses

Response samples

PUT complete

Responses

Response samples

GET my football stats

Responses

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required

`path Parameters`

`Responses`

`Response samples`

`GET correct leaderboard`

`path Parameters`

`Responses`

`Response samples`

`GET ratio leaderboard`

`path Parameters`

`Responses`

`Response samples`

`PUT yardline`

`path Parameters`

`Responses`

`Response samples`

`PUT complete`

`Responses`

`Response samples`

`GET my football stats`

`Responses`

`Response samples`