Votes and followers

Votes and followers of a post, including votes on behalf of your customers.

Set up the SDK client used in the examples

API key or Dashboard session:

import { UpVoiced } from '@upvoiced/sdk';

const apiKey = process.env['UPVOICED_API_KEY']; // uv_live_… (Settings → API keys)
const workspace = process.env['UPVOICED_WORKSPACE_ID']; // sent as X-Workspace
if (!apiKey || !workspace) throw new Error('Set UPVOICED_API_KEY and UPVOICED_WORKSPACE_ID.');
const upvoiced = new UpVoiced({ apiKey, workspace });

curl examples read $UPVOICED_API_KEY and $UPVOICED_WORKSPACE_IDfrom your shell. MCP examples are the tools/call request an MCP client sends to the MCP server with the same API key.

GET`/v1/posts/{id}/followers`

Followers with reason (author/vote/comment/manual) and mute state

Authentication: API key or Dashboard session; API key scope read
Operation id: listFollowers

Path parameters
Name	Type	Required
`id`	`string (uuid)`	Yes

Query parameters
Name	Type	Required
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–100default 50	No

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes

Response 200: 8 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].end_user_id`	`string (uuid)`	Yes
`items[].email`	`string \| null`	Yes
`items[].name`	`string \| null`	Yes
`items[].reason`	`"author" \| "vote" \| "comment" \| "manual"`	Yes
`items[].muted`	`boolean`	Yes
`items[].created_at`	`string (date-time)`	Yes
`next_cursor`	`string \| null`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl 'https://api.upvoiced.com/v1/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/followers' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

const data = await upvoiced.get('/v1/posts/{id}/followers', { path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' } });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/posts/{id}/followers`

Follow on behalf of an end-user by email (find-or-create); set muted

Authentication: API key or Dashboard session; API key scope write
Operation id: addFollower
Idempotency: Send an Idempotency-Key to make retries safe.

Path parameters
Name	Type	Required
`id`	`string (uuid)`	Yes

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`email`	`string (email)`length ≤ 254	Yes
`muted`	`boolean`	No

Response 200: 8 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].end_user_id`	`string (uuid)`	Yes
`items[].email`	`string \| null`	Yes
`items[].name`	`string \| null`	Yes
`items[].reason`	`"author" \| "vote" \| "comment" \| "manual"`	Yes
`items[].muted`	`boolean`	Yes
`items[].created_at`	`string (date-time)`	Yes
`next_cursor`	`string \| null`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/followers' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/posts/{id}/followers', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { email: 'ada@example.com' },
});

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

DELETE`/v1/posts/{id}/followers`

Unfollow an end-user by email (idempotent)

Authentication: API key or Dashboard session; API key scope write
Operation id: removeFollower

Path parameters
Name	Type	Required
`id`	`string (uuid)`	Yes

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes

Request body (JSON)
Name	Type	Required
`email`	`string (email)`length ≤ 254	Yes

Response 200: 8 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].end_user_id`	`string (uuid)`	Yes
`items[].email`	`string \| null`	Yes
`items[].name`	`string \| null`	Yes
`items[].reason`	`"author" \| "vote" \| "comment" \| "manual"`	Yes
`items[].muted`	`boolean`	Yes
`items[].created_at`	`string (date-time)`	Yes
`next_cursor`	`string \| null`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X DELETE 'https://api.upvoiced.com/v1/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/followers' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com"
}'

TypeScript SDK

const data = await upvoiced.delete('/v1/posts/{id}/followers', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { email: 'ada@example.com' },
});

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/posts/{id}/votes`

Record a vote on behalf of an end-user by email (source api; one per end-user)

Authentication: API key or Dashboard session; API key scope write
Operation id: addVote
Idempotency: Send an Idempotency-Key to make retries safe.

Path parameters
Name	Type	Required
`id`	`string (uuid)`	Yes

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`email`	`string (email)`length ≤ 254	Yes
`weight`	`integer`value 1–10	No

Response 200: 5 fields

Response 200 (application/json)
Name	Type	Required
`post_id`	`string (uuid)`	Yes
`end_user_id`	`string (uuid)`	Yes
`voted`	`boolean`	Yes
`weight`	`integer \| null`value ≥ 1	Yes
`vote_count`	`integer`value ≥ 0	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/votes' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/posts/{id}/votes', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { email: 'ada@example.com' },
});

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

DELETE`/v1/posts/{id}/votes`

Remove an end-user's vote (idempotent unvote)

Authentication: API key or Dashboard session; API key scope write
Operation id: removeVote

Path parameters
Name	Type	Required
`id`	`string (uuid)`	Yes

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes

Request body (JSON)
Name	Type	Required
`email`	`string (email)`length ≤ 254	Yes

Response 200: 5 fields

Response 200 (application/json)
Name	Type	Required
`post_id`	`string (uuid)`	Yes
`end_user_id`	`string (uuid)`	Yes
`voted`	`boolean`	Yes
`weight`	`integer \| null`value ≥ 1	Yes
`vote_count`	`integer`value ≥ 0	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X DELETE 'https://api.upvoiced.com/v1/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/votes' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com"
}'

TypeScript SDK

const data = await upvoiced.delete('/v1/posts/{id}/votes', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { email: 'ada@example.com' },
});

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

Votes and followers

GET/v1/posts/{id}/followers

POST/v1/posts/{id}/followers

DELETE/v1/posts/{id}/followers

POST/v1/posts/{id}/votes

DELETE/v1/posts/{id}/votes

GET`/v1/posts/{id}/followers`

POST`/v1/posts/{id}/followers`

DELETE`/v1/posts/{id}/followers`

POST`/v1/posts/{id}/votes`

DELETE`/v1/posts/{id}/votes`