Custom fields

Typed fields on posts (text, number, currency, select), operator-only or public, optionally filled from SSO attributes.

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/custom-fields`

List the custom post field definitions in display order (any member)

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

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

Response 200: 16 fields

Response 200 (application/json)
Name	Type	Required
`items`	`array of object`items ≤ 20	Yes
`items[].id`	`string (uuid)`	Yes
`items[].key`	`string`pattern ^[a-z][a-z0-9_]{0,39}$	Yes
`items[].name`	`string`	Yes
`items[].description`	`string`	Yes
`items[].type`	`"text" \| "number" \| "currency" \| "select"`	Yes
`items[].currency`	`string \| null`pattern ^[A-Z]{3}$	Yes
`items[].options`	`array of object`	Yes
`items[].options[].value`	`string`pattern ^[a-z0-9][a-z0-9_-]{0,63}$	Yes
`items[].options[].label`	`string`length 1–100	Yes
`items[].visibility`	`"operator" \| "public"`	Yes
`items[].sso_attribute`	`string \| null`pattern ^[A-Za-z][A-Za-z0-9_.-]{0,63}$	Yes
`items[].position`	`integer`	Yes
`items[].weightable`	`boolean`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].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 'https://api.upvoiced.com/v1/custom-fields' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

const data = await upvoiced.get('/v1/custom-fields');

MCP

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

POST`/v1/custom-fields`

Define a custom post field: text, number, currency or select; at most 20 per workspace; optionally filled from an SSO attribute (owner/admin)

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

Request body (JSON)
Name	Type	Required
`key`	`string`pattern ^[a-z][a-z0-9_]{0,39}$	Yes
`name`	`string`length 1–60	Yes
`description`	`string`length ≤ 280default ""	No
`type`	`"text" \| "number" \| "currency" \| "select"`	Yes
`currency`	`string`pattern ^[A-Z]{3}$	No
`options`	`array of object`items 1–50	No
`options[].value`	`string`pattern ^[a-z0-9][a-z0-9_-]{0,63}$	Yes
`options[].label`	`string`length 1–100	Yes
`visibility`	`"operator" \| "public"`default "operator"	No
`sso_attribute`	`string \| null`pattern ^[A-Za-z][A-Za-z0-9_.-]{0,63}$default null	No
`position`	`integer`value 0–1000default 0	No

Response 201: 15 fields

Response 201 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`key`	`string`pattern ^[a-z][a-z0-9_]{0,39}$	Yes
`name`	`string`	Yes
`description`	`string`	Yes
`type`	`"text" \| "number" \| "currency" \| "select"`	Yes
`currency`	`string \| null`pattern ^[A-Z]{3}$	Yes
`options`	`array of object`	Yes
`options[].value`	`string`pattern ^[a-z0-9][a-z0-9_-]{0,63}$	Yes
`options[].label`	`string`length 1–100	Yes
`visibility`	`"operator" \| "public"`	Yes
`sso_attribute`	`string \| null`pattern ^[A-Za-z][A-Za-z0-9_.-]{0,63}$	Yes
`position`	`integer`	Yes
`weightable`	`boolean`	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/custom-fields' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "acme",
  "name": "Example",
  "type": "text"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/custom-fields', { body: { key: 'acme', name: 'Example', type: 'text' } });

MCP

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

GET`/v1/custom-fields/{id}`

Get one custom post field definition (any member)

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

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

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

Response 200: 15 fields

Response 200 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`key`	`string`pattern ^[a-z][a-z0-9_]{0,39}$	Yes
`name`	`string`	Yes
`description`	`string`	Yes
`type`	`"text" \| "number" \| "currency" \| "select"`	Yes
`currency`	`string \| null`pattern ^[A-Z]{3}$	Yes
`options`	`array of object`	Yes
`options[].value`	`string`pattern ^[a-z0-9][a-z0-9_-]{0,63}$	Yes
`options[].label`	`string`length 1–100	Yes
`visibility`	`"operator" \| "public"`	Yes
`sso_attribute`	`string \| null`pattern ^[A-Za-z][A-Za-z0-9_.-]{0,63}$	Yes
`position`	`integer`	Yes
`weightable`	`boolean`	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 'https://api.upvoiced.com/v1/custom-fields/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

PATCH`/v1/custom-fields/{id}`

Rename, re-describe, reorder, change visibility, options (select) or the SSO attribute of a custom field; removed options are cleared from posts (owner/admin)

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

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

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

Request body (JSON)
Name	Type	Required
`name`	`string`length 1–60	No
`description`	`string`length ≤ 280	No
`options`	`array of object`items 1–50	No
`options[].value`	`string`pattern ^[a-z0-9][a-z0-9_-]{0,63}$	Yes
`options[].label`	`string`length 1–100	Yes
`visibility`	`"operator" \| "public"`	No
`sso_attribute`	`string \| null`pattern ^[A-Za-z][A-Za-z0-9_.-]{0,63}$	No
`position`	`integer`value 0–1000	No

Response 200: 15 fields

Response 200 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`key`	`string`pattern ^[a-z][a-z0-9_]{0,39}$	Yes
`name`	`string`	Yes
`description`	`string`	Yes
`type`	`"text" \| "number" \| "currency" \| "select"`	Yes
`currency`	`string \| null`pattern ^[A-Z]{3}$	Yes
`options`	`array of object`	Yes
`options[].value`	`string`pattern ^[a-z0-9][a-z0-9_-]{0,63}$	Yes
`options[].label`	`string`length 1–100	Yes
`visibility`	`"operator" \| "public"`	Yes
`sso_attribute`	`string \| null`pattern ^[A-Za-z][A-Za-z0-9_.-]{0,63}$	Yes
`position`	`integer`	Yes
`weightable`	`boolean`	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 PATCH 'https://api.upvoiced.com/v1/custom-fields/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example"
}'

TypeScript SDK

const data = await upvoiced.patch('/v1/custom-fields/{id}', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: { name: 'Example' },
});

MCP

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

DELETE`/v1/custom-fields/{id}`

Delete a custom field and clear its value from every post (owner/admin)

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

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/custom-fields/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/custom-fields/{id}', { path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' } });

MCP

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

Custom fields

GET/v1/custom-fields

POST/v1/custom-fields

GET/v1/custom-fields/{id}

PATCH/v1/custom-fields/{id}

DELETE/v1/custom-fields/{id}

GET`/v1/custom-fields`

POST`/v1/custom-fields`

GET`/v1/custom-fields/{id}`

PATCH`/v1/custom-fields/{id}`

DELETE`/v1/custom-fields/{id}`