Moderation

Reports, held comments and blocked end users.

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/reports`

Moderation queue: end-user reports of posts and comments by status (default open), newest first, with the target excerpt, its author (keyed IP hash, blocked flag) and open report count

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

Query parameters
Name	Type	Required
`status`	`"open" \| "resolved" \| "dismissed"`default "open"	No
`cursor`	`string`length 1–512	No
`limit`	`integer`value 1–100default 25	No

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

Response 200: 17 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].id`	`string (uuid)`	Yes
`items[].target`	`object`	Yes
`items[].target.kind`	`"post" \| "comment"`	Yes
`items[].target.post_id`	`string (uuid)`	Yes
`items[].target.comment_id`	`string (uuid) \| null`	Yes
`items[].target.excerpt`	`string \| null`length ≤ 280	Yes
`items[].target.deleted`	`boolean`	Yes
`items[].target.author`	`object`	Yes
`items[].target.open_reports`	`integer`value ≥ 0	Yes
`items[].reason`	`"spam" \| "abuse" \| "off_topic" \| "other"`	Yes
`items[].note`	`string \| null`length ≤ 500	Yes
`items[].reporter_end_user_id`	`string (uuid)`	Yes
`items[].status`	`"open" \| "resolved" \| "dismissed"`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].resolved_at`	`string (date-time) \| null`	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/reports' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

POST`/v1/reports/{id}/resolve`

Resolve or dismiss a report: closes every open report of the same post or comment (remove content or block the author with their own routes)

Authentication: API key or Dashboard session; API key scope write
Operation id: resolveReport
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
`status`	`"resolved" \| "dismissed"`	Yes

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`closed`	`integer`value ≥ 0	Yes
`status`	`"resolved" \| "dismissed"`	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/reports/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/resolve' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "resolved"
}'

TypeScript SDK

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

MCP

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

GET`/v1/held-comments`

End-user comments held for approval (over the link threshold), newest first; not visible anywhere until approved

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

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

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

Response 200: 15 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[].body_md`	`string`	Yes
`items[].reason`	`"links"`	Yes
`items[].link_count`	`integer`value ≥ 0	Yes
`items[].author`	`object`	Yes
`items[].author.end_user_id`	`string (uuid) \| null`	Yes
`items[].author.name`	`string \| null`length 1–100	Yes
`items[].author.email`	`string \| null`length ≤ 254	Yes
`items[].author.ip_hash`	`string \| null`pattern ^[0-9a-f]{32}$	Yes
`items[].author.blocked`	`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/held-comments' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

const data = await upvoiced.get('/v1/held-comments');

MCP

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

POST`/v1/held-comments/{id}/approve`

Publish a held comment as its author (normal checks, follower notifications from now on)

Authentication: API key or Dashboard session; API key scope write
Operation id: approveHeldComment
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

Response 200: 14 fields

Response 200 (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.id`	`string (uuid) \| null`	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
`updated_at`	`string (date-time)`	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/held-comments/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/approve' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

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

Reject a held comment: it is deleted and never published

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

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

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

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 DELETE 'https://api.upvoiced.com/v1/held-comments/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

const data = await upvoiced.delete('/v1/held-comments/{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/blocks`

Block list: end-users, email addresses, email domains and keyed IP hashes refused on every end-user write (owner/admin)

Authentication: API key or Dashboard session; API key scope admin
Operation id: listBlocks

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

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

Response 200: 10 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`	Yes
`items[].id`	`string (uuid)`	Yes
`items[].kind`	`"end_user" \| "email" \| "email_domain" \| "ip_hash"`	Yes
`items[].value`	`string`length ≤ 254	Yes
`items[].end_user_id`	`string (uuid) \| null`	Yes
`items[].reason`	`string \| null`length ≤ 500	Yes
`items[].expires_at`	`string (date-time) \| null`	Yes
`items[].created_by_operator_id`	`string (uuid)`	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/blocks' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

POST`/v1/blocks`

Block an end-user, an email address, an email domain (subdomains included) or a keyed IP hash, optionally until a time; idempotent per subject (owner/admin)

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

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

Response 201: 8 fields

Response 201 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`kind`	`"end_user" \| "email" \| "email_domain" \| "ip_hash"`	Yes
`value`	`string`length ≤ 254	Yes
`end_user_id`	`string (uuid) \| null`	Yes
`reason`	`string \| null`length ≤ 500	Yes
`expires_at`	`string (date-time) \| null`	Yes
`created_by_operator_id`	`string (uuid)`	Yes
`created_at`	`string (date-time)`	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/blocks' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "end_user",
  "end_user_id": "0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/blocks', {
  body: {
    kind: 'end_user',
    end_user_id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d',
  },
});

MCP

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

DELETE`/v1/blocks/{id}`

Remove a block (owner/admin)

Authentication: API key or Dashboard session; API key scope admin
Operation id: deleteBlock

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

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

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 DELETE 'https://api.upvoiced.com/v1/blocks/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

Moderation

GET/v1/reports

POST/v1/reports/{id}/resolve

GET/v1/held-comments

POST/v1/held-comments/{id}/approve

DELETE/v1/held-comments/{id}

GET/v1/blocks

POST/v1/blocks

DELETE/v1/blocks/{id}

GET`/v1/reports`

POST`/v1/reports/{id}/resolve`

GET`/v1/held-comments`

POST`/v1/held-comments/{id}/approve`

DELETE`/v1/held-comments/{id}`

GET`/v1/blocks`

POST`/v1/blocks`

DELETE`/v1/blocks/{id}`