API docs by Redocly

Board Game Manager Backend (0.1.0)

Download OpenAPI specification:

Tiago Sousa: tiago.costa.sousa@proton.me URL: https://github.com/tiago-cos

Simple API where users can create and manage board games with layouts, tiles, and rules.

Checkout the project repository for more information.

Games

List games

Retrieve a paginated list of game IDs representing the games created by the specified user, ordered by most recent first.

Visibility Rules:

  • If the authenticated user is the same as the user whose games are being requested, the list includes all games (public and private).
  • If the authenticated user is different, the list includes only public games.

Pagination:

  • Pagination starts at page 1 by default.
  • page controls which page of results is returned.
  • size controls how many game IDs are included per page.
Authorizations:
boardToken
query Parameters
search
string

Filter games by title prefix (case-insensitive).

user_id
string <uuid>
Example: user_id=abcd1234-ef56-7890-ab12-cd34567890ef

The UUID of the user whose games are being retrieved.

page
integer
Default: 1
Example: page=1

The page number to retrieve (starting at 1).

size
integer
Default: 10
Example: size=10

Number of items per page.

Responses

Response samples

Content type
application/json
{
  • "games": [
    ],
  • "page_size": 3,
  • "total_elements": 12,
  • "total_pages": 4,
  • "current_page": 1
}

Create game

Create a new game owned by the specified user.

Note:

  • The title must not exceed 100 characters.
  • The description must not exceed 1024 characters.
Authorizations:
boardToken
Request Body schema: application/json
required

JSON object containing the new game's details.

title
required
string <= 100 characters

The title of the new game.

description
required
string <= 1024 characters

A short description of the new game.

owner_id
required
string <uuid>

The UUID of the user creating the game.

Responses

Request samples

Content type
application/json
{
  • "title": "Mystic Maze",
  • "description": "A cooperative board game where players navigate a shifting labyrinth.",
  • "owner_id": "a47621ad-59bf-4674-a6f2-5e7d9abf9faf"
}

Response samples

Content type
application/json
"64a75816-1f79-4c6d-806c-2e6667b74d2b"

Get game

Retrieve detailed information for a specific game.

Note:

  • The response includes a public flag indicating whether the game is publicly visible.
  • You can only retrieve details for public games or private games that you own.
  • Only games with public: true appear in other users' timelines.
Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 82633550-7105-40b8-aef1-9bd640a5a606

The UUID of the game to retrieve.

Responses

Response samples

Content type
application/json
{
  • "title": "Mystic Maze",
  • "description": "A cooperative board game where players navigate a shifting labyrinth.",
  • "public": true,
  • "owner_id": "77cdb643-94a7-419f-9916-970c79d012e8"
}

Patch game

Partially update one or more fields of a specific game.

Note:

  • Any combination of title, description, and public may be provided.
  • The title must not exceed 100 characters.
  • The description must not exceed 1024 characters.
  • The public flag can only be set to true if the game already has a board and rules defined.
Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 64a75816-1f79-4c6d-806c-2e6667b74d2b

The UUID of the game to update.

Request Body schema: application/json
required

JSON object containing one or more fields to update.

title
string <= 100 characters

The new title of the game.

description
string <= 1024 characters

The new description of the game.

public
boolean

Set to true to make the game publicly visible (only allowed if the game has a board and rules).

Responses

Request samples

Content type
application/json
{
  • "title": "Mystic Maze: Deluxe Edition",
  • "public": true
}

Delete game

Permanently delete a game.

Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 64a75816-1f79-4c6d-806c-2e6667b74d2b

The UUID of the game to delete.

Responses

Boards

Add or update a game board

Add or replace the board of the specified game. This operation is idempotent and will fully replace any existing board.

Requirements:

  • height and width must each be an integer between 5 and 20.
  • The start and end objects must each contain valid x and y coordinates within the board's dimensions.
  • Each board piece must include:
    • x and y coordinates (0-indexed) within the board's bounds.
    • A color value of red, green, blue, or yellow.
    • A type value of plain, star, circle, or square.
  • All coordinates must fit within the specified board dimensions.
  • No two pieces may overlap, including the start and end positions.
Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 64a75816-1f79-4c6d-806c-2e6667b74d2b

The UUID of the game whose board is being added or updated.

Request Body schema: application/json
required

JSON object describing the new or updated board.

height
required
integer [ 5 .. 20 ]

Height of the board.

width
required
integer [ 5 .. 20 ]

Width of the board.

required
object

Coordinates of the start piece.

required
object

Coordinates of the end piece.

required
Array of objects

Array of board pieces.

Responses

Request samples

Content type
application/json
{
  • "height": 8,
  • "width": 8,
  • "start": {
    },
  • "end": {
    },
  • "pieces": [
    ]
}

Get a game board

Retrieve the board of the specified game, including its dimensions, start and end positions, and all board pieces.

Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 64a75816-1f79-4c6d-806c-2e6667b74d2b

The UUID of the game whose board is being retrieved.

Responses

Response samples

Content type
application/json
{
  • "height": 8,
  • "width": 8,
  • "start": {
    },
  • "end": {
    },
  • "pieces": [
    ]
}

Rules

Add or update game rules

Add or replace the list of rules for the specified game.

Note:

  • This operation is idempotent; sending the same set of rules multiple times will not create duplicates.
  • All rules must be provided each time to fully replace the current set.
Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 64a75816-1f79-4c6d-806c-2e6667b74d2b

The UUID of the game whose rules are being added or updated.

Request Body schema: application/json
required

JSON array of rules to assign to the game.

Array
string

Responses

Request samples

Content type
application/json
[
  • "Players can move up to two tiles at a time.",
  • "Blue tiles make players return to start.",
  • "Star tiles skip the player's next turn."
]

Get game rules

Retrieve the list of rules for the specified game.

Authorizations:
boardToken
path Parameters
game_id
required
string
Example: 64a75816-1f79-4c6d-806c-2e6667b74d2b

The UUID of the game whose rules are being retrieved.

Responses

Response samples

Content type
application/json
[
  • "Players can move up to two tiles at a time.",
  • "Blue tiles make players return to start.",
  • "Star tiles skip the player's next turn."
]

Authentication

Register

Register a new user.

Note:

  • The username and password must not contain special characters.
  • The username must not exceed 20 characters.
  • The password must not exceed 256 characters.
Request Body schema: application/json
required

Request body for adding a new user.

username
required
string <= 20 characters

The username of the new user.

password
required
string <= 256 characters

The password of the new user.

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "password": "password123"
}

Response samples

Content type
application/json
{
  • "jwt_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5SnliMnhsSWpwN0lsVnpaWElpT2lKaFpHRm1JbjBzSW1WNGNDSTZNVGN6T0RFNE1UTTNNWDAuZExmYWJFVnJ6VXI1eTgwNTlFTUl0dC1VLXhoc2lQWlFYU3R5WUo4Q29hYw==",
  • "refresh_token": "ez6K5tTdum8rAOdCV4vdoyuSxDeALroCDrJyR4n8JcMtJIHWbH3IJfz1cWp0mx5k",
  • "user_id": "2c5f1d4d-3b9d-4b9d-3b9d-4b9d3b9d3b9d"
}

Login

Login with a user's credentials.

Request Body schema: application/json
required

Request body for logging in a user.

username
required
string

The username of the user,

password
required
string

The password of the user.

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "password": "password123"
}

Response samples

Content type
application/json
{
  • "jwt_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5SnliMnhsSWpwN0lsVnpaWElpT2lKaFpHRm1JbjBzSW1WNGNDSTZNVGN6T0RFNE1UTTNNWDAuZExmYWJFVnJ6VXI1eTgwNTlFTUl0dC1VLXhoc2lQWlFYU3R5WUo4Q29hYw==",
  • "refresh_token": "ez6K5tTdum8rAOdCV4vdoyuSxDeALroCDrJyR4n8JcMtJIHWbH3IJfz1cWp0mx5k",
  • "user_id": "2c5f1d4d-3b9d-4b9d-3b9d-4b9d3b9d3b9d"
}

Logout

Invalidate a user's refresh token, effectively logging them out.

Request Body schema: application/json
required
refresh_token
required
string

The refresh token to invalidate.

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "eKxEETPjUDfvvY1oxcCRboHn88GsggBoyoyiSAUJ37FAeZquv8BwruAl6I6Pc8wJ"
}

Refresh access token

Exchange a valid refresh token for a new access token and a rotated refresh token.
The old token becomes invalid after refreshing.

Request Body schema: application/json
required

Request body containing the refresh token.

refresh_token
required
string

The refresh token issued during login or previous refresh.

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "ez6K5tTdum8rAOdCV4vdoyuSxDeALroCDrJyR4n8JcMtJIHWbH3IJfz1cWp0mx5k"
}

Response samples

Content type
application/json
{
  • "jwt_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5SnliMnhsSWpwN0lsVnpaWElpT2lKaFpHRm1JbjBzSW1WNGNDSTZNVGN6T0RFNE1UTTNNWDAuZExmYWJFVnJ6VXI1eTgwNTlFTUl0dC1VLXhoc2lQWlFYU3R5WUo4Q29hYw==",
  • "refresh_token": "ez6K5tTdum8rAOdCV4vdoyuSxDeALroCDrJyR4n8JcMtJIHWbH3IJfz1cWp0mx5k",
  • "user_id": "2c5f1d4d-3b9d-4b9d-3b9d-4b9d3b9d3b9d"
}

Profile

Search users

Retrieve a paginated list of user IDs (UUIDs).

Search:

  • If a search query parameter is provided, only users whose usernames start with the given string (case-insensitive) will be returned.
  • If no search parameter is provided, all user IDs are returned.

Pagination:

  • Pagination starts at page 1 by default.
  • page controls which page of results is returned.
  • size controls how many user IDs are included per page.
Authorizations:
boardToken
query Parameters
search
string
Example: search=alex

Filter users by username prefix (case-insensitive).

page
integer
Default: 1
Example: page=1

The page number to retrieve (starting at 1).

size
integer
Default: 10
Example: size=10

Number of items per page.

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "page_size": 3,
  • "total_elements": 25,
  • "total_pages": 9,
  • "current_page": 1
}

Get user profile

Retrieve profile information for a user by their internal UUID.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose profile is being retrieved.

Responses

Response samples

Content type
application/json
{
  • "username": "john.doe",
  • "description": "Avid board game designer and weekend hiker."
}

Update user profile

Replace all profile information for the specified user.

Note:

  • The username must not contain special characters and must not exceed 20 characters.
  • The description must not exceed 512 characters.
Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose profile is being updated.

Request Body schema: application/json
required

New profile information to assign to the user.

username
required
string <= 20 characters

The username of the user.

description
required
string <= 512 characters

A short "about me" text to display on the user’s profile.

Responses

Request samples

Content type
application/json
{
  • "username": "john.doe",
  • "description": "Avid board game designer and weekend hiker."
}

Picture

Get user profile picture

Retrieve the profile picture of a user by their internal UUID.
The image is returned as binary data (e.g., JPEG or PNG).
Optional query parameters can be used to request a specific size; if omitted, the original image size is returned.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose profile picture is being retrieved.

query Parameters
height
integer [ 1 .. 1000 ]

Desired height of the image in pixels. Defaults to the original image height if not provided.

width
integer [ 1 .. 1000 ]

Desired width of the image in pixels. Defaults to the original image width if not provided.

Responses

Update user profile picture

Upload and replace the profile picture for the specified user.

Note:

  • The provided image must be less than 5 MB in size.
  • The provided image must have a square (1:1) aspect ratio.
  • Only JPEG or PNG formats are accepted.
Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose profile picture is being updated.

Request Body schema:
required

JPEG or PNG image to set as the new profile picture.

Schema not provided

Responses

Delete user profile picture

Remove the current profile picture of the specified user.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose profile picture is being deleted.

Responses

Followers

Get followers

Retrieve a list of user IDs representing the users who are following the specified user.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose followers list is being retrieved.

Responses

Response samples

Content type
application/json
[
  • "550e8400-e29b-41d4-a716-4466554403g71",
  • "09fe5ae2-1c52-44fb-ab99-9e24807322bf",
  • "7db4de36-17a2-4dd4-8a45-83c2399e3c18"
]

Get following

Retrieve a list of user IDs representing the users that the specified user is following.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose list of followed users is being retrieved.

Responses

Response samples

Content type
application/json
[
  • "84e66bd2-f511-42ec-89db-be23b598e4c7",
  • "74d8b3d5-0c5d-49e7-b46b-7547f8647e77",
  • "d0280967-f710-45c0-a9c4-09cb358b74b8"
]

Follow another user

Make the specified user follow the target user.
If the user is already following the target, this operation is idempotent.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

UUID of the following user.

Request Body schema: application/json
required

UUID of the user to follow

target_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "target_id": "a47621ad-59bf-4674-a6f2-5e7d9abf9faf"
}

Unfollow another user

Make the specified user unfollow the target user.
If the user is not currently following the target, this operation is idempotent.

Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

UUID of the following user.

target_id
required
string

UUID of the user to unfollow.

Responses

Timeline

Get user timeline

Retrieve a paginated list of game IDs representing the games that should appear in the specified user's timeline.

A user's timeline is calculated by merging the IDs of all the public games of the users that the specified user is following, ordered by most recent.

Note:

  • Pagination starts at page 1 by default.
  • page controls which page of results is returned.
  • size controls how many game IDs are included per page.
Authorizations:
boardToken
path Parameters
user_id
required
string <uuid>
Example: a47621ad-59bf-4674-a6f2-5e7d9abf9faf

The UUID of the user whose timeline is being retrieved.

query Parameters
page
integer
Default: 1
Example: page=1

The page number to retrieve (starting at 1).

size
integer
Default: 10
Example: size=10

Number of items per page.

Responses

Response samples

Content type
application/json
{
  • "games": [
    ],
  • "page_size": 3,
  • "total_elements": 7,
  • "total_pages": 3,
  • "current_page": 1
}