Widget API

What the feedback widget calls with a signed-in end user’s session: posting, voting, following, comments and the user’s own data.

Set up the SDK client used in the examples

End-user session (widget):

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

// End-user operations: the session token the widget received when the user signed in.
const upvoiced = new UpVoiced({
  headers: { authorization: `Bearer ${endUserToken}` },
  workspace: 'acme', // your workspace slug
});

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/widget/me`

The signed-in end-user, the session expiry and the unread state: changelog dot, status changes since the last visit

Authentication: End-user session (widget)
Operation id: getMe

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 18 fields

Response 200 (application/json)
Name	Type	Required
`end_user`	`object`	Yes
`end_user.id`	`string (uuid)`	Yes
`end_user.email`	`string \| null`length ≤ 254	Yes
`end_user.name`	`string \| null`length 1–100	Yes
`end_user.avatar_url`	`string \| null`length ≤ 2048	Yes
`end_user.locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	Yes
`end_user.created_at`	`string (date-time)`	Yes
`session`	`object`	Yes
`session.expires_at`	`string (date-time)`	Yes
`unread`	`object`	Yes
`unread.changelog`	`object`	Yes
`unread.changelog.unread`	`boolean`	Yes
`unread.changelog.unread_count`	`integer`value 0–99	Yes
`unread.changelog.last_seen_at`	`string (date-time) \| null`	Yes
`unread.changelog.latest_published_at`	`string (date-time) \| null`	Yes
`unread.status_changes`	`object`	Yes
`unread.status_changes.count`	`integer`value 0–99	Yes
`unread.status_changes.last_seen_at`	`string (date-time) \| 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/widget/me' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/me');

MCP

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

POST`/v1/widget/auth/logout`

Revoke the presented session (idempotent)

Authentication: End-user session (widget)
Operation id: logout
Idempotency: Send an Idempotency-Key to make retries safe.

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 1 fields

Response 200 (application/json)
Name	Type	Required
`ok`	`true`	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/widget/auth/logout' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/auth/logout', { body: {} });

MCP

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

POST`/v1/widget/changelog/seen`

The end-user opened the changelog now: clears the unread dot

Authentication: End-user session (widget)
Operation id: markChangelogSeen
Idempotency: Send an Idempotency-Key to make retries safe.

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 8 fields

Response 200 (application/json)
Name	Type	Required
`changelog`	`object`	Yes
`changelog.unread`	`boolean`	Yes
`changelog.unread_count`	`integer`value 0–99	Yes
`changelog.last_seen_at`	`string (date-time) \| null`	Yes
`changelog.latest_published_at`	`string (date-time) \| null`	Yes
`status_changes`	`object`	Yes
`status_changes.count`	`integer`value 0–99	Yes
`status_changes.last_seen_at`	`string (date-time) \| 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/widget/changelog/seen' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/changelog/seen', { body: {} });

MCP

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

POST`/v1/widget/updates/seen`

The end-user saw the status changes of followed/voted posts now: resets the count

Authentication: End-user session (widget)
Operation id: markUpdatesSeen
Idempotency: Send an Idempotency-Key to make retries safe.

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 8 fields

Response 200 (application/json)
Name	Type	Required
`changelog`	`object`	Yes
`changelog.unread`	`boolean`	Yes
`changelog.unread_count`	`integer`value 0–99	Yes
`changelog.last_seen_at`	`string (date-time) \| null`	Yes
`changelog.latest_published_at`	`string (date-time) \| null`	Yes
`status_changes`	`object`	Yes
`status_changes.count`	`integer`value 0–99	Yes
`status_changes.last_seen_at`	`string (date-time) \| 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/widget/updates/seen' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/updates/seen', { body: {} });

MCP

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

POST`/v1/widget/me/delete`

Delete my data: anonymized within 24 h, 30 days at most (end-user session)

Authentication: End-user session (widget)
Operation id: deleteMyData
Idempotency: Send an Idempotency-Key to make retries safe.

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 202: 3 fields

Response 202 (application/json)
Name	Type	Required
`status`	`"pending" \| "processing" \| "completed"`	Yes
`due_at`	`string (date-time)`	Yes
`confirmation_email`	`boolean`	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/widget/me/delete' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/me/delete', { body: {} });

MCP

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

GET`/v1/widget/me/votes`

Posts I voted for that I can still read, newest vote first

Authentication: End-user session (widget)
Operation id: listMyVotes

Query parameters
Name	Type	Required
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–50default 20	No
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 34 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`items ≤ 50	Yes
`items[].id`	`string (uuid)`	Yes
`items[].board_id`	`string (uuid)`	Yes
`items[].slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`items[].title`	`string`length 1–140	Yes
`items[].body_md`	`string`length ≤ 10000	Yes
`items[].status`	`object`	Yes
`items[].status.id`	`string (uuid)`	Yes
`items[].status.name`	`string`length 1–100	Yes
`items[].status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`items[].tags`	`array of object`items ≤ 50	Yes
`items[].tags[].id`	`string (uuid)`	Yes
`items[].tags[].name`	`string`length 1–100	Yes
`items[].tags[].color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].images`	`array of object`items ≤ 4	Yes
`items[].images[].id`	`string (uuid)`	Yes
`items[].images[].url`	`string (uri)`	Yes
`items[].images[].mime`	`"image/png" \| "image/jpeg" \| "image/webp"`	Yes
`items[].images[].bytes`	`integer`value ≤ 5242880value > 0	Yes
`items[].author`	`object`	Yes
`items[].author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`items[].author.name`	`string \| null`length 1–100	Yes
`items[].vote_count`	`integer`value ≥ 0	Yes
`items[].comment_count`	`integer`value ≥ 0	Yes
`items[].merged_into_post_id`	`string (uuid) \| null`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].updated_at`	`string (date-time)`	Yes
`items[].approved`	`boolean`	Yes
`items[].viewer`	`object`	Yes
`items[].viewer.voted`	`boolean`	Yes
`items[].viewer.following`	`boolean`	Yes
`items[].viewer.is_author`	`boolean`	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/widget/me/votes' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/me/votes');

MCP

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

GET`/v1/widget/me/follows`

Posts I follow (not muted) that I can still read, newest follow first

Authentication: End-user session (widget)
Operation id: listMyFollows

Query parameters
Name	Type	Required
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–50default 20	No
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 34 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`items ≤ 50	Yes
`items[].id`	`string (uuid)`	Yes
`items[].board_id`	`string (uuid)`	Yes
`items[].slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`items[].title`	`string`length 1–140	Yes
`items[].body_md`	`string`length ≤ 10000	Yes
`items[].status`	`object`	Yes
`items[].status.id`	`string (uuid)`	Yes
`items[].status.name`	`string`length 1–100	Yes
`items[].status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`items[].tags`	`array of object`items ≤ 50	Yes
`items[].tags[].id`	`string (uuid)`	Yes
`items[].tags[].name`	`string`length 1–100	Yes
`items[].tags[].color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].images`	`array of object`items ≤ 4	Yes
`items[].images[].id`	`string (uuid)`	Yes
`items[].images[].url`	`string (uri)`	Yes
`items[].images[].mime`	`"image/png" \| "image/jpeg" \| "image/webp"`	Yes
`items[].images[].bytes`	`integer`value ≤ 5242880value > 0	Yes
`items[].author`	`object`	Yes
`items[].author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`items[].author.name`	`string \| null`length 1–100	Yes
`items[].vote_count`	`integer`value ≥ 0	Yes
`items[].comment_count`	`integer`value ≥ 0	Yes
`items[].merged_into_post_id`	`string (uuid) \| null`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].updated_at`	`string (date-time)`	Yes
`items[].approved`	`boolean`	Yes
`items[].viewer`	`object`	Yes
`items[].viewer.voted`	`boolean`	Yes
`items[].viewer.following`	`boolean`	Yes
`items[].viewer.is_author`	`boolean`	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/widget/me/follows' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/me/follows');

MCP

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

GET`/v1/widget/me/preferences`

My email preferences in this workspace: the P1-007 opt-outs shared with unsubscribe links

Authentication: End-user session (widget)
Operation id: getMyPreferences

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 6 fields

Response 200 (application/json)
Name	Type	Required
`email`	`object`	Yes
`email.followed`	`boolean`	Yes
`email.changelog`	`boolean`	Yes
`email.surveys`	`boolean`	Yes
`email.testimonials`	`boolean`	Yes
`workspace_emails_enabled`	`boolean`	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/widget/me/preferences' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/me/preferences');

MCP

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

PATCH`/v1/widget/me/preferences`

Turn email categories on or off: followed posts, changelog, surveys, testimonial requests

Authentication: End-user session (widget)
Operation id: updateMyPreferences

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Request body (JSON)
Name	Type	Required
`email`	`object`	Yes
`email.followed`	`boolean`	No
`email.changelog`	`boolean`	No
`email.surveys`	`boolean`	No
`email.testimonials`	`boolean`	No

Response 200: 6 fields

Response 200 (application/json)
Name	Type	Required
`email`	`object`	Yes
`email.followed`	`boolean`	Yes
`email.changelog`	`boolean`	Yes
`email.surveys`	`boolean`	Yes
`email.testimonials`	`boolean`	Yes
`workspace_emails_enabled`	`boolean`	Yes

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

curl

curl -X PATCH 'https://api.upvoiced.com/v1/widget/me/preferences' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Content-Type: application/json" \
  -d '{
  "email": {
    "followed": true
  }
}'

TypeScript SDK

const data = await upvoiced.patch('/v1/widget/me/preferences', { body: { email: { followed: true } } });

MCP

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

POST`/v1/widget/me/export`

My own records in this workspace as JSON: profile, preferences, posts, comments, votes, follows; 5 per hour

Authentication: End-user session (widget)
Operation id: exportMyData

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 47 fields

Response 200 (application/json)
Name	Type	Required
`format`	`"upvoiced.end_user_export.v1"`	Yes
`exported_at`	`string (date-time)`	Yes
`workspace`	`object`	Yes
`workspace.name`	`string`	Yes
`workspace.slug`	`string`	Yes
`profile`	`object`	Yes
`profile.id`	`string (uuid)`	Yes
`profile.email`	`string \| null`	Yes
`profile.name`	`string \| null`	Yes
`profile.avatar_url`	`string \| null`	Yes
`profile.locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	Yes
`profile.created_at`	`string (date-time)`	Yes
`profile.identity_verified_at`	`string (date-time) \| null`	Yes
`profile.last_seen_at`	`string (date-time) \| null`	Yes
`email_preferences`	`object`	Yes
`email_preferences.followed`	`boolean`	Yes
`email_preferences.changelog`	`boolean`	Yes
`email_preferences.surveys`	`boolean`	Yes
`email_preferences.testimonials`	`boolean`	Yes
`posts`	`array of object`	Yes
`posts[].id`	`string (uuid)`	Yes
`posts[].title`	`string`	Yes
`posts[].body_md`	`string`	Yes
`posts[].board`	`string \| null`	Yes
`posts[].status`	`string`	Yes
`posts[].approved`	`boolean`	Yes
`posts[].on_my_behalf`	`boolean`	Yes
`posts[].created_at`	`string (date-time)`	Yes
`posts[].deleted`	`boolean`	Yes
`comments`	`array of object`	Yes
`comments[].id`	`string (uuid)`	Yes
`comments[].post_id`	`string (uuid)`	Yes
`comments[].post_title`	`string \| null`	Yes
`comments[].body_md`	`string`	Yes
`comments[].created_at`	`string (date-time)`	Yes
`comments[].edited_at`	`string (date-time) \| null`	Yes
`comments[].deleted_at`	`string (date-time) \| null`	Yes
`votes`	`array of object`	Yes
`votes[].post_id`	`string (uuid)`	Yes
`votes[].post_title`	`string \| null`	Yes
`votes[].created_at`	`string (date-time)`	Yes
`follows`	`array of object`	Yes
`follows[].post_id`	`string (uuid)`	Yes
`follows[].post_title`	`string \| null`	Yes
`follows[].muted`	`boolean`	Yes
`follows[].created_at`	`string (date-time)`	Yes
`truncated`	`boolean`	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/widget/me/export' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/me/export', { body: {} });

MCP

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

GET`/v1/widget/me/posts`

My posts, newest first, including ones awaiting approval

Authentication: End-user session (widget)
Operation id: listMyPosts

Query parameters
Name	Type	Required
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–50default 20	No
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 34 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`items ≤ 50	Yes
`items[].id`	`string (uuid)`	Yes
`items[].board_id`	`string (uuid)`	Yes
`items[].slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`items[].title`	`string`length 1–140	Yes
`items[].body_md`	`string`length ≤ 10000	Yes
`items[].status`	`object`	Yes
`items[].status.id`	`string (uuid)`	Yes
`items[].status.name`	`string`length 1–100	Yes
`items[].status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`items[].tags`	`array of object`items ≤ 50	Yes
`items[].tags[].id`	`string (uuid)`	Yes
`items[].tags[].name`	`string`length 1–100	Yes
`items[].tags[].color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].images`	`array of object`items ≤ 4	Yes
`items[].images[].id`	`string (uuid)`	Yes
`items[].images[].url`	`string (uri)`	Yes
`items[].images[].mime`	`"image/png" \| "image/jpeg" \| "image/webp"`	Yes
`items[].images[].bytes`	`integer`value ≤ 5242880value > 0	Yes
`items[].author`	`object`	Yes
`items[].author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`items[].author.name`	`string \| null`length 1–100	Yes
`items[].vote_count`	`integer`value ≥ 0	Yes
`items[].comment_count`	`integer`value ≥ 0	Yes
`items[].merged_into_post_id`	`string (uuid) \| null`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].updated_at`	`string (date-time)`	Yes
`items[].approved`	`boolean`	Yes
`items[].viewer`	`object`	Yes
`items[].viewer.voted`	`boolean`	Yes
`items[].viewer.following`	`boolean`	Yes
`items[].viewer.is_author`	`boolean`	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/widget/me/posts' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/me/posts');

MCP

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

GET`/v1/widget/boards`

Public boards the end-user can browse and post to

Authentication: End-user session (widget)
Operation id: listWidgetBoards

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 7 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].id`	`string (uuid)`	Yes
`items[].name`	`string`length 1–100	Yes
`items[].slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`items[].description`	`string`length ≤ 2000	Yes
`items[].visibility`	`"public"`	Yes
`items[].require_approval`	`boolean`	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/widget/boards' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/boards');

MCP

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

GET`/v1/widget/posts`

Posts of one board with my vote/follow state; own unapproved posts included

Authentication: End-user session (widget)
Operation id: listWidgetPosts

Query parameters
Name	Type	Required
`board`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No
`sort`	`"trending" \| "top" \| "new" \| "relevance"`	No
`status`	`string (uuid)`	No
`tag`	`string (uuid)`	No
`q`	`string`length 1–200	No
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–50default 20	No
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 34 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`items ≤ 50	Yes
`items[].id`	`string (uuid)`	Yes
`items[].board_id`	`string (uuid)`	Yes
`items[].slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`items[].title`	`string`length 1–140	Yes
`items[].body_md`	`string`length ≤ 10000	Yes
`items[].status`	`object`	Yes
`items[].status.id`	`string (uuid)`	Yes
`items[].status.name`	`string`length 1–100	Yes
`items[].status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`items[].tags`	`array of object`items ≤ 50	Yes
`items[].tags[].id`	`string (uuid)`	Yes
`items[].tags[].name`	`string`length 1–100	Yes
`items[].tags[].color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].images`	`array of object`items ≤ 4	Yes
`items[].images[].id`	`string (uuid)`	Yes
`items[].images[].url`	`string (uri)`	Yes
`items[].images[].mime`	`"image/png" \| "image/jpeg" \| "image/webp"`	Yes
`items[].images[].bytes`	`integer`value ≤ 5242880value > 0	Yes
`items[].author`	`object`	Yes
`items[].author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`items[].author.name`	`string \| null`length 1–100	Yes
`items[].vote_count`	`integer`value ≥ 0	Yes
`items[].comment_count`	`integer`value ≥ 0	Yes
`items[].merged_into_post_id`	`string (uuid) \| null`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].updated_at`	`string (date-time)`	Yes
`items[].approved`	`boolean`	Yes
`items[].viewer`	`object`	Yes
`items[].viewer.voted`	`boolean`	Yes
`items[].viewer.following`	`boolean`	Yes
`items[].viewer.is_author`	`boolean`	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/widget/posts' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/posts');

MCP

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

POST`/v1/widget/posts`

Submit a post; approval-required boards keep it visible to its author only

Authentication: End-user session (widget)
Operation id: createWidgetPost
Idempotency: Send an Idempotency-Key to make retries safe.

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`board_id`	`string (uuid)`	Yes
`title`	`string`length 1–140	Yes
`body_md`	`string`length ≤ 10000default ""	No
`website`	`string`length ≤ 2048	No

Response 201: 32 fields

Response 201 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`board_id`	`string (uuid)`	Yes
`slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`title`	`string`length 1–140	Yes
`body_md`	`string`length ≤ 10000	Yes
`status`	`object`	Yes
`status.id`	`string (uuid)`	Yes
`status.name`	`string`length 1–100	Yes
`status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`tags`	`array of object`items ≤ 50	Yes
`tags[].id`	`string (uuid)`	Yes
`tags[].name`	`string`length 1–100	Yes
`tags[].color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`images`	`array of object`items ≤ 4	Yes
`images[].id`	`string (uuid)`	Yes
`images[].url`	`string (uri)`	Yes
`images[].mime`	`"image/png" \| "image/jpeg" \| "image/webp"`	Yes
`images[].bytes`	`integer`value ≤ 5242880value > 0	Yes
`author`	`object`	Yes
`author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`author.name`	`string \| null`length 1–100	Yes
`vote_count`	`integer`value ≥ 0	Yes
`comment_count`	`integer`value ≥ 0	Yes
`merged_into_post_id`	`string (uuid) \| null`	Yes
`created_at`	`string (date-time)`	Yes
`updated_at`	`string (date-time)`	Yes
`approved`	`boolean`	Yes
`viewer`	`object`	Yes
`viewer.voted`	`boolean`	Yes
`viewer.following`	`boolean`	Yes
`viewer.is_author`	`boolean`	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/widget/posts' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "board_id": "0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d",
  "title": "Dark mode"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/posts', {
  body: {
    board_id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d',
    title: 'Dark mode',
  },
});

MCP

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

GET`/v1/widget/posts/similar`

Duplicate hints while typing a title, up to 5

Authentication: End-user session (widget)
Operation id: listWidgetSimilarPosts

Query parameters
Name	Type	Required
`q`	`string`length ≤ 200	Yes
`board`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 12 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`items ≤ 5	Yes
`items[].id`	`string (uuid)`	Yes
`items[].board_id`	`string (uuid)`	Yes
`items[].slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`items[].title`	`string`length 1–140	Yes
`items[].status`	`object`	Yes
`items[].status.id`	`string (uuid)`	Yes
`items[].status.name`	`string`length 1–100	Yes
`items[].status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`items[].status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`items[].vote_count`	`integer`value ≥ 0	Yes
`items[].score`	`number`value 0–1	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/widget/posts/similar?q=dark+mode' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/posts/similar', { query: { q: 'dark mode' } });

MCP

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

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

Post detail with my state, the official reply and the first comments

Authentication: End-user session (widget)
Operation id: getWidgetPost

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 63 fields

Response 200 (application/json)
Name	Type	Required
`post`	`object`	Yes
`post.id`	`string (uuid)`	Yes
`post.board_id`	`string (uuid)`	Yes
`post.slug`	`string`length 1–200pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$	Yes
`post.title`	`string`length 1–140	Yes
`post.body_md`	`string`length ≤ 10000	Yes
`post.status`	`object`	Yes
`post.status.id`	`string (uuid)`	Yes
`post.status.name`	`string`length 1–100	Yes
`post.status.color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`post.status.category`	`"open" \| "active" \| "done" \| "closed"`	Yes
`post.tags`	`array of object`items ≤ 50	Yes
`post.tags[].id`	`string (uuid)`	Yes
`post.tags[].name`	`string`length 1–100	Yes
`post.tags[].color`	`string`pattern ^#[0-9a-fA-F]{6}$	Yes
`post.images`	`array of object`items ≤ 4	Yes
`post.images[].id`	`string (uuid)`	Yes
`post.images[].url`	`string (uri)`	Yes
`post.images[].mime`	`"image/png" \| "image/jpeg" \| "image/webp"`	Yes
`post.images[].bytes`	`integer`value ≤ 5242880value > 0	Yes
`post.author`	`object`	Yes
`post.author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`post.author.name`	`string \| null`length 1–100	Yes
`post.vote_count`	`integer`value ≥ 0	Yes
`post.comment_count`	`integer`value ≥ 0	Yes
`post.merged_into_post_id`	`string (uuid) \| null`	Yes
`post.created_at`	`string (date-time)`	Yes
`post.updated_at`	`string (date-time)`	Yes
`post.approved`	`boolean`	Yes
`post.viewer`	`object`	Yes
`post.viewer.voted`	`boolean`	Yes
`post.viewer.following`	`boolean`	Yes
`post.viewer.is_author`	`boolean`	Yes
`official_reply`	`object \| null`	Yes
`official_reply.id`	`string (uuid)`	Yes
`official_reply.post_id`	`string (uuid)`	Yes
`official_reply.parent_id`	`string (uuid) \| null`	Yes
`official_reply.author`	`object`	Yes
`official_reply.author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`official_reply.author.name`	`string \| null`length ≤ 200	Yes
`official_reply.body_md`	`string`	Yes
`official_reply.is_official`	`boolean`	Yes
`official_reply.pinned`	`boolean`	Yes
`official_reply.edited_at`	`string (date-time) \| null`	Yes
`official_reply.deleted_at`	`string (date-time) \| null`	Yes
`official_reply.created_at`	`string (date-time)`	Yes
`official_reply.is_mine`	`boolean`	Yes
`official_reply.held`	`true`	No
`comments`	`object`	Yes
`comments.items`	`array of object`	Yes
`comments.items[].id`	`string (uuid)`	Yes
`comments.items[].post_id`	`string (uuid)`	Yes
`comments.items[].parent_id`	`string (uuid) \| null`	Yes
`comments.items[].author`	`object`	Yes
`comments.items[].body_md`	`string`	Yes
`comments.items[].is_official`	`boolean`	Yes
`comments.items[].pinned`	`boolean`	Yes
`comments.items[].edited_at`	`string (date-time) \| null`	Yes
`comments.items[].deleted_at`	`string (date-time) \| null`	Yes
`comments.items[].created_at`	`string (date-time)`	Yes
`comments.items[].is_mine`	`boolean`	Yes
`comments.items[].held`	`true`	No
`comments.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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

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

MCP

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

GET`/v1/widget/posts/{id}/comments`

Comments of a readable post, oldest first

Authentication: End-user session (widget)
Operation id: listWidgetComments

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

Query parameters
Name	Type	Required
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–50default 20	No
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 16 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].id`	`string (uuid)`	Yes
`items[].post_id`	`string (uuid)`	Yes
`items[].parent_id`	`string (uuid) \| null`	Yes
`items[].author`	`object`	Yes
`items[].author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`items[].author.name`	`string \| null`length ≤ 200	Yes
`items[].body_md`	`string`	Yes
`items[].is_official`	`boolean`	Yes
`items[].pinned`	`boolean`	Yes
`items[].edited_at`	`string (date-time) \| null`	Yes
`items[].deleted_at`	`string (date-time) \| null`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].is_mine`	`boolean`	Yes
`items[].held`	`true`	No
`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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/comments' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/posts/{id}/comments', { 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/widget/posts/{id}/comments`

Comment or reply one level; markdown subset, sanitized on render

Authentication: End-user session (widget)
Operation id: commentWidgetPost
Idempotency: Send an Idempotency-Key to make retries safe.

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`body_md`	`string`length ≤ 10000	Yes
`parent_id`	`string (uuid)`	No
`website`	`string`length ≤ 2048	No

Response 201: 14 fields

Response 201 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`post_id`	`string (uuid)`	Yes
`parent_id`	`string (uuid) \| null`	Yes
`author`	`object`	Yes
`author.kind`	`"operator" \| "end_user" \| "deleted"`	Yes
`author.name`	`string \| null`length ≤ 200	Yes
`body_md`	`string`	Yes
`is_official`	`boolean`	Yes
`pinned`	`boolean`	Yes
`edited_at`	`string (date-time) \| null`	Yes
`deleted_at`	`string (date-time) \| null`	Yes
`created_at`	`string (date-time)`	Yes
`is_mine`	`boolean`	Yes
`held`	`true`	No

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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/comments' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body_md": "It would help our night shift."
}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/posts/{id}/comments', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { body_md: 'It would help our night shift.' },
});

MCP

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

POST`/v1/widget/posts/{id}/vote`

Vote once (repeat is a no-op); follows the post

Authentication: End-user session (widget)
Operation id: voteWidgetPost
Idempotency: Send an Idempotency-Key to make retries safe.

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 3 fields

Response 200 (application/json)
Name	Type	Required
`post_id`	`string (uuid)`	Yes
`voted`	`boolean`	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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/vote' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

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

MCP

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

DELETE`/v1/widget/posts/{id}/vote`

Remove my vote (idempotent; the follow stays)

Authentication: End-user session (widget)
Operation id: unvoteWidgetPost

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 3 fields

Response 200 (application/json)
Name	Type	Required
`post_id`	`string (uuid)`	Yes
`voted`	`boolean`	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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/vote' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.delete('/v1/widget/posts/{id}/vote', { 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/widget/posts/{id}/follow`

Follow a post for status/comment emails

Authentication: End-user session (widget)
Operation id: followWidgetPost
Idempotency: Send an Idempotency-Key to make retries safe.

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`post_id`	`string (uuid)`	Yes
`following`	`boolean`	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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/follow' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

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

MCP

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

DELETE`/v1/widget/posts/{id}/follow`

Stop following a post (idempotent)

Authentication: End-user session (widget)
Operation id: unfollowWidgetPost

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`post_id`	`string (uuid)`	Yes
`following`	`boolean`	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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/follow' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

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

MCP

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

GET`/v1/widget/changelog/subscription`

Whether I get changelog emails (subscribed and the changelog category on)

Authentication: End-user session (widget)
Operation id: getChangelogSubscription

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 200: 1 fields

Response 200 (application/json)
Name	Type	Required
`subscribed`	`boolean`	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/widget/changelog/subscription' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme"

TypeScript SDK

const data = await upvoiced.get('/v1/widget/changelog/subscription');

MCP

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

POST`/v1/widget/changelog/subscription`

Subscribe or unsubscribe my account to changelog emails (idempotent; needs an email address)

Authentication: End-user session (widget)
Operation id: setChangelogSubscription
Idempotency: Send an Idempotency-Key to make retries safe.

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`subscribed`	`boolean`	Yes

Response 200: 1 fields

Response 200 (application/json)
Name	Type	Required
`subscribed`	`boolean`	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/widget/changelog/subscription' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "subscribed": true
}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/changelog/subscription', { body: { subscribed: true } });

MCP

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

POST`/v1/widget/changelog/{id}/react`

Set or clear my 👍 ❤️ 🎉 reaction on a published entry; one per end-user and emoji, counts operator-only

Authentication: End-user session (widget)
Operation id: reactWidgetChangelog
Idempotency: Send an Idempotency-Key to make retries safe.

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`emoji`	`"👍" \| "❤️" \| "🎉"`	Yes
`reacted`	`boolean`default true	No

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`entry_id`	`string (uuid)`	Yes
`reactions`	`array of "👍" \| "❤️" \| "🎉"`items ≤ 3	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/widget/changelog/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/react' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "emoji": "👍"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/changelog/{id}/react', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { emoji: '👍' },
});

MCP

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

POST`/v1/widget/posts/{id}/report`

Report a post to the moderators (spam, abuse, off topic, other); one report per end-user and post, always the same answer

Authentication: End-user session (widget)
Operation id: reportWidgetPost
Idempotency: Send an Idempotency-Key to make retries safe.

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`reason`	`"spam" \| "abuse" \| "off_topic" \| "other"`	Yes
`note`	`string`length ≤ 500	No

Response 202: 1 fields

Response 202 (application/json)
Name	Type	Required
`reported`	`true`	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/widget/posts/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/report' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "spam"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/posts/{id}/report', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { reason: 'spam' },
});

MCP

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

POST`/v1/widget/comments/{id}/report`

Report a comment to the moderators; one report per end-user and comment, always the same answer

Authentication: End-user session (widget)
Operation id: reportWidgetComment
Idempotency: Send an Idempotency-Key to make retries safe.

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

Query parameters
Name	Type	Required
`workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No

Headers
Name	Type	Required
`x-workspace`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`reason`	`"spam" \| "abuse" \| "off_topic" \| "other"`	Yes
`note`	`string`length ≤ 500	No

Response 202: 1 fields

Response 202 (application/json)
Name	Type	Required
`reported`	`true`	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/widget/comments/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/report' \
  -H "Authorization: Bearer $UPVOICED_END_USER_TOKEN" \
  -H "X-Workspace: acme" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "spam"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/widget/comments/{id}/report', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { reason: 'spam' },
});

MCP

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

Widget API

GET/v1/widget/me

POST/v1/widget/auth/logout

POST/v1/widget/changelog/seen

POST/v1/widget/updates/seen

POST/v1/widget/me/delete

GET/v1/widget/me/votes

GET/v1/widget/me/follows

GET/v1/widget/me/preferences

PATCH/v1/widget/me/preferences

POST/v1/widget/me/export

GET/v1/widget/me/posts

GET/v1/widget/boards

GET/v1/widget/posts

POST/v1/widget/posts

GET/v1/widget/posts/similar

GET/v1/widget/posts/{id}

GET/v1/widget/posts/{id}/comments

POST/v1/widget/posts/{id}/comments

POST/v1/widget/posts/{id}/vote

DELETE/v1/widget/posts/{id}/vote

POST/v1/widget/posts/{id}/follow

DELETE/v1/widget/posts/{id}/follow

GET/v1/widget/changelog/subscription

POST/v1/widget/changelog/subscription

POST/v1/widget/changelog/{id}/react

POST/v1/widget/posts/{id}/report

POST/v1/widget/comments/{id}/report

GET`/v1/widget/me`

POST`/v1/widget/auth/logout`

POST`/v1/widget/changelog/seen`

POST`/v1/widget/updates/seen`

POST`/v1/widget/me/delete`

GET`/v1/widget/me/votes`

GET`/v1/widget/me/follows`

GET`/v1/widget/me/preferences`

PATCH`/v1/widget/me/preferences`

POST`/v1/widget/me/export`

GET`/v1/widget/me/posts`

GET`/v1/widget/boards`

GET`/v1/widget/posts`

POST`/v1/widget/posts`

GET`/v1/widget/posts/similar`

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

GET`/v1/widget/posts/{id}/comments`

POST`/v1/widget/posts/{id}/comments`

POST`/v1/widget/posts/{id}/vote`

DELETE`/v1/widget/posts/{id}/vote`

POST`/v1/widget/posts/{id}/follow`

DELETE`/v1/widget/posts/{id}/follow`

GET`/v1/widget/changelog/subscription`

POST`/v1/widget/changelog/subscription`

POST`/v1/widget/changelog/{id}/react`

POST`/v1/widget/posts/{id}/report`

POST`/v1/widget/comments/{id}/report`