Voting API

Voting allows team members to collectively curate the best definitions. Each user can cast one vote (upvote or downvote) per definition. Voting again with the same direction removes the vote (toggle behavior).

Cast Vote

POST /api/v1/acronyms/{acronymId}/definitions/{defId}/vote

Casts or toggles a vote on a definition.

Parameters

Parameter	Type	Required	Description
acronymId	string	Yes	The acronym ID (e.g., `acr_abc123def456`)
defId	string	Yes	The definition ID (e.g., `def_xyz789`)

Request Body

{
  "value": 1
}

Body Parameters

Field	Type	Required	Values	Description
value	number	Yes	`1` or `-1`	1 for upvote, -1 for downvote

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "upvotes": 15,
    "downvotes": 2,
    "netVotes": 13,
    "userVote": 1
  }
}

Response Fields

Field	Type	Description
upvotes	number	Total upvotes on this definition
downvotes	number	Total downvotes on this definition
netVotes	number	upvotes - downvotes
userVote	number \| null	Your current vote (1, -1, or null)

Toggle Behavior

If you vote with the same direction twice, your vote is removed:

First vote (upvote):

curl -X POST https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_xyz789/vote \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": 1}'

Response:

{
  "success": true,
  "data": {
    "upvotes": 15,
    "downvotes": 2,
    "netVotes": 13,
    "userVote": 1
  }
}

Same vote again (removes vote):

curl -X POST https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_xyz789/vote \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": 1}'

Response:

{
  "success": true,
  "data": {
    "upvotes": 14,
    "downvotes": 2,
    "netVotes": 12,
    "userVote": null
  }
}

Changing Your Vote

You can change your vote by voting in the opposite direction:

Current vote is upvote (1), switch to downvote (-1):

curl -X POST https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_xyz789/vote \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": -1}'

Response:

{
  "success": true,
  "data": {
    "upvotes": 14,
    "downvotes": 3,
    "netVotes": 11,
    "userVote": -1
  }
}

Examples

Upvote a definition:

curl -X POST https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_xyz789/vote \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": 1}'

Downvote a definition:

curl -X POST https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_xyz789/vote \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": -1}'

Remove Vote

DELETE /api/v1/acronyms/{acronymId}/definitions/{defId}/vote

Removes your vote from a definition.

Parameters

Parameter	Type	Required	Description
acronymId	string	Yes	The acronym ID
defId	string	Yes	The definition ID

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "upvotes": 14,
    "downvotes": 2,
    "netVotes": 12,
    "userVote": null
  }
}

Example

curl -X DELETE https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_xyz789/vote \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Vote Counting

Definition Votes

Each definition maintains separate upvote and downvote counts. The net votes are calculated as:

netVotes = upvotes - downvotes

Acronym Votes

When listing acronyms, the total votes displayed is the sum across all definitions:

totalVotes = sum of netVotes from all definitions

Ranking

Definitions are ranked by:

Primary definitions first
Net votes (highest to lowest)
Creation date (oldest to newest as tiebreaker)

Vote-Based Features

Negative Sentiment Flag

Acronyms with definitions that have negative votes (downvotes > upvotes) are flagged:

{
  "hasNegativeVotes": true
}

You can filter for problematic acronyms using the sentiment=negative query parameter:

curl "https://engineering.define.wtf/api/v1/acronyms?sentiment=negative" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Gamification Points

Casting a vote awards 1 point in the gamification system. Your total points are tracked in your user profile.

Permissions

All authenticated users can vote
Voting is optional — no permission required to read definitions without voting
One vote per definition per user — you cannot vote twice on the same definition

Error Responses

Definition not found (404):

{
  "success": false,
  "error": {
    "code": "DEFINITION_NOT_FOUND",
    "message": "Definition not found"
  }
}

Acronym not found (404):

{
  "success": false,
  "error": {
    "code": "ACRONYM_NOT_FOUND",
    "message": "Acronym not found"
  }
}

Invalid vote value (400):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "value": ["Expected 1 or -1"]
    }
  }
}

Unauthorized (401):

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required to vote"
  }
}

Vote Activity

All votes are tracked for:

Audit logging — admins can see who voted on what
Gamification points — users earn 1 point per vote
Activity streams — team members see voting activity in their feeds

Soft-deleted definitions still retain their votes, but votes are removed if the definition is permanently deleted.

Voting

On this page