Users

All endpoints are prefixed with /api/users. Responses use Content-Type: application/json. Endpoints that return or modify private data require an Authorization: Bearer <accessToken> header.

GET /api/users/me

Return the full profile of the currently authenticated user, including their aura points, streak, completion count, and leaderboard rank.

Auth required: Yes — include Authorization: Bearer <accessToken>.

Response — 200 OK

success

boolean

true on success.

data

object

Show properties

integer

User ID.

string

Email address.

name

string

Display name.

role

string

user or admin.

auraPoints

integer

Total aura points earned.

streak

integer

Current consecutive-day completion streak.

lastCompletedAt

string | null

ISO 8601 timestamp of the most recent completion, or null if none.

createdAt

string

ISO 8601 account creation timestamp.

completionsCount

integer

Total number of challenges completed.

rank

integer

The user’s current leaderboard rank (1 = highest aura points).

Error responses

Status	Condition
`401`	Missing or invalid Bearer token
`404`	User record not found

Example

curl http://localhost:3000/api/users/me \
  -H "Authorization: Bearer <accessToken>"

PATCH /api/users/me

Update the display name and/or email address of the currently authenticated user. At least one updatable field must be provided.

Auth required: Yes — include Authorization: Bearer <accessToken>.

Request body

name

string

New display name. 1–100 characters. Whitespace is trimmed.

string

New email address. Must be a valid email, maximum 255 characters. Stored in lowercase.

Response — 200 OK

success

boolean

true on success.

message

string

"Profile updated successfully"

data

object

The full updated user record from the database.

Show properties

integer

User ID.

string

Updated email address.

name

string

Updated display name.

role

string

user or admin.

auraPoints

integer

Total aura points.

streak

integer

Current streak.

lastCompletedAt

string | null

Last completion timestamp.

createdAt

string

Account creation timestamp.

Error responses

Status	Condition
`400`	No valid fields provided, or validation failure
`401`	Missing or invalid Bearer token
`404`	User record not found
`409`	The supplied email is already in use by another account

Example

curl -X PATCH http://localhost:3000/api/users/me \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"name": "Mustang Mike"}'

GET /api/users/:id

Return the public profile of any user by their numeric ID.

Path parameters

integer

required

The numeric ID of the user.

Response — 200 OK

success

boolean

true on success.

data

object

Show properties

integer

User ID.

string

Email address.

name

string

Display name.

role

string

user or admin.

auraPoints

integer

Total aura points earned.

streak

integer

Current streak.

lastCompletedAt

string | null

Last completion timestamp.

createdAt

string

ISO 8601 account creation timestamp.

completionsCount

integer

Total challenges completed.

Error responses

Status	Condition
`400`	`id` is not a valid integer
`404`	No user found with that ID

Example

curl "http://localhost:3000/api/users/7"

GET /api/users/:id/completions

Return all challenge completions for the specified user, ordered by most recent first. Each completion includes the full challenge record.

Path parameters

integer

required

The numeric ID of the user.

Response — 200 OK

success

boolean

true on success.

data

array

Completions sorted by completedAt descending.

Show completion properties

integer

Completion ID.

userId

integer

User ID.

challengeId

integer

Challenge ID.

latitude

number

Latitude at completion.

longitude

number

Longitude at completion.

imageUrl

string | null

Proof photo URL.

imageUri

string

Proof photo URI.

caption

string | null

Optional caption.

completedAt

string

ISO 8601 completion timestamp.

likes

integer

Like count.

challenge

object

Full challenge record for the completed challenge. See GET /api/challenges/:id for field details.

flags

array

Flags reported on this completion, each including the flaggedBy user record.

Error responses

Status	Condition
`400`	`id` is not a valid integer
`404`	No user found with that ID

Example

curl "http://localhost:3000/api/users/7/completions"

GET /api/users/:id/stats

Return aggregated statistics for a user, including breakdowns by difficulty, streak history, and recent activity.

Path parameters

integer

required

The numeric ID of the user.

Response — 200 OK

success

boolean

true on success.

data

object

Show properties

userId

integer

User ID.

totalCompletions

integer

Total number of challenges completed.

auraPoints

integer

Total aura points earned.

currentStreak

integer

Current consecutive-day streak.

longestStreak

integer

Longest consecutive-day streak ever recorded for this user.

completionsByDifficulty

object

Show properties

easy

integer

Completions on easy challenges.

medium

integer

Completions on medium challenges.

hard

integer

Completions on hard challenges.

pointsByDifficulty

object

Show properties

easy

integer

Points earned from easy challenges.

medium

integer

Points earned from medium challenges.

hard

integer

Points earned from hard challenges.

activity

object

Show properties

completedThisWeek

integer

Completions in the last 7 days.

completedThisMonth

integer

Completions in the last 30 days.

averagePointsPerCompletion

integer

Mean aura points per completed challenge (rounded to the nearest integer).

Error responses

Status	Condition
`400`	`id` is not a valid integer
`404`	No user found with that ID

Example

curl "http://localhost:3000/api/users/7/stats"

Overview

Endpoints

GET /api/users/me

Response — 200 OK

Error responses

Example

PATCH /api/users/me

Request body

Response — 200 OK

Error responses

Example

GET /api/users/:id

Path parameters

Response — 200 OK

Error responses

Example

GET /api/users/:id/completions

Path parameters

Response — 200 OK

Error responses

Example

GET /api/users/:id/stats

Path parameters

Response — 200 OK

Error responses

Example

Build docs developers (and LLMs) love

Overview

Endpoints

​GET /api/users/me

​Response — 200 OK

​Error responses

​Example

​PATCH /api/users/me

​Request body

​Response — 200 OK

​Error responses

​Example

​GET /api/users/:id

​Path parameters

​Response — 200 OK

​Error responses

​Example

​GET /api/users/:id/completions

​Path parameters

​Response — 200 OK

​Error responses

​Example

​GET /api/users/:id/stats

​Path parameters

​Response — 200 OK

​Error responses

​Example

Build docs developers (and LLMs) love

GET /api/users/me

Response — 200 OK

Error responses

Example

PATCH /api/users/me

Request body

Response — 200 OK

Error responses

Example

GET /api/users/:id

Path parameters

Response — 200 OK

Error responses

Example

GET /api/users/:id/completions

Path parameters

Response — 200 OK

Error responses

Example

GET /api/users/:id/stats

Path parameters

Response — 200 OK

Error responses

Example