Image Voting Vote Endpoint

Last updated: January 26, 2026

Route

POST /wp-json/extrachill/v1/image-voting/vote

Purpose

Cast a vote in an image voting block instance. This endpoint allows visitors to vote on images in polls embedded in posts, returning updated vote totals.

Permission

POST: Public (no authentication required, anonymous voting supported)

POST Request

{
  "post_id": 42,
  "instance_id": "img_voting_block_1",
  "image_id": "option_2"
}

Request Parameters

Parameter	Type	Required	Notes
`post_id`	integer	Yes	WordPress post ID containing the image voting block
`instance_id`	string	Yes	Unique identifier for this specific block instance (generated by block)
`image_id`	string	Yes	ID of the image option being voted for

POST Response

{
  "voted": true,
  "vote_totals": {
    "option_1": 45,
    "option_2": 67,
    "option_3": 23
  }
}

The response includes the vote status and updated totals for all options in the voting instance.

Error Codes

Code	Status	Description
`invalid_post_id`	400	Post ID is invalid or missing
`invalid_instance_id`	400	Instance ID is invalid or missing
`invalid_image_id`	400	Image ID is invalid or missing
`post_not_found`	404	Post with given ID does not exist
`block_not_found`	404	Image voting block instance not found in post
`database_error`	500	Failed to record vote

Implementation Notes

Votes are stored anonymously by default (IP address or session ID, depending on configuration)
One vote per visitor per instance (duplicate votes overwrite previous votes from same source)
Vote counts are returned immediately after vote is recorded
The voting data is stored persistently and survives page refreshes
Voting is enabled on all sites in the network without authentication

Related Endpoints

GET /blog/image-voting/vote-count/{post_id}/{instance_id} – Retrieve current vote counts without voting

Usage Examples

Cast a Vote

curl -X POST "http://site.local/wp-json/extrachill/v1/image-voting/vote" 
  -H "Content-Type: application/json" 
  -d '{
    "post_id": 42,
    "instance_id": "img_voting_block_1",
    "image_id": "option_2"
  }'

Vote on Different Image

curl -X POST "http://site.local/wp-json/extrachill/v1/image-voting/vote" 
  -H "Content-Type: application/json" 
  -d '{
    "post_id": 42,
    "instance_id": "img_voting_block_1",
    "image_id": "option_3"
  }'

Frontend Integration

The ExtraChill Blog "Image Voting" block calls this endpoint when a visitor clicks an image option, updating the vote display in real-time without page reload.

Vote Persistence

Votes are attributed to the visitor (typically by IP or session)
Changing vote for same block instance updates the previous vote (one vote per visitor per instance)
Vote data persists across browser sessions
Voting history is not exposed to prevent gaming the voting system