Grails API Documentation

POST /api/v1/votes

Cast, update, or remove a vote on an ENS name. Each user can have one vote per name. Voting is idempotent — re-submitting the same vote has no effect, and changing vote value updates it in place.

Authentication: Required

Cache: None

Request Body

Field	Type	Required	Description
`ensName`	string	Yes	ENS name to vote on
`vote`	number	Yes	`1` = upvote, `-1` = downvote, `0` = remove vote

Sample Request


curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.grails.app/api/v1/votes \
  -d '{ "ensName": "example.eth", "vote": 1 }'

Response


// 200 OK
{
  "success": true,
  "data": {
    "vote": {
      "id": 1,
      "ensNameId": 42,
      "userId": 1,
      "vote": 1,
      "createdAt": "2026-04-08T00:00:00.000Z",
      "updatedAt": "2026-04-08T00:00:00.000Z"
    },
    "voteCounts": {
      "upvotes": 15,
      "downvotes": 3,
      "netScore": 12
    }
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body
401	`UNAUTHORIZED`	Missing or invalid token
404	`ENS_NAME_NOT_FOUND`	ENS name not found
500	`INTERNAL_ERROR`	Failed to cast vote