Workspace

The workspace itself: settings, single sign-on, widget settings, deletion and restore.

Set up the SDK client used in the examples

Dashboard session only (API keys get 403 session_required):

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

// Dashboard-session operations: the Clerk session token of a signed-in operator.
const upvoiced = new UpVoiced({
  headers: { authorization: `Bearer ${sessionToken}` },
  workspace: workspaceId,
});

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

List the caller's active workspaces

Authentication: Dashboard session only (API keys get 403 session_required)
Operation id: listWorkspaces

Response 200: 8 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[].portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	Yes
`items[].created_at`	`string (date-time)`	Yes
`items[].updated_at`	`string (date-time)`	Yes
`next_cursor`	`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/workspaces' \
  -H "Authorization: Bearer $UPVOICED_SESSION_TOKEN"

TypeScript SDK

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

MCP

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

POST`/v1/workspaces`

Create a workspace owned by the caller

Authentication: Dashboard session only (API keys get 403 session_required)
Operation id: createWorkspace
Idempotency: Send an Idempotency-Key to make retries safe.

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

Request body (JSON)
Name	Type	Required
`name`	`string`length 1–100	Yes
`slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`default "en"	No
`accent`	`string`pattern ^#[0-9a-fA-F]{6}$	No
`attribution`	`object`	No
`attribution.utm_source`	`string \| null`length ≤ 100pattern ^[\w.-]+$	Yes
`attribution.utm_medium`	`string \| null`length ≤ 100pattern ^[\w.-]+$	Yes
`attribution.utm_campaign`	`string \| null`length ≤ 100pattern ^[\w.-]+$	Yes
`attribution.utm_term`	`string \| null`length ≤ 100pattern ^[\w.-]+$	No
`attribution.utm_content`	`string \| null`length ≤ 100pattern ^[\w.-]+$	No
`attribution.referrer_domain`	`string \| null`length ≤ 253pattern ^[a-z0-9.-]*$	Yes
`attribution.landing_path`	`string \| null`length ≤ 512pattern ^\/[^?#\s]*$	Yes

Response 201: 6 fields

Response 201 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`name`	`string`length 1–100	Yes
`slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	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/workspaces' \
  -H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example",
  "slug": "dark-mode"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/workspaces', { body: { name: 'Example', slug: 'dark-mode' } });

MCP

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

GET`/v1/workspace`

Get the selected workspace

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

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

Response 200: 6 fields

Response 200 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`name`	`string`length 1–100	Yes
`slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	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/workspace' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_workspaces",
    "arguments": {}
  }
}

Tool list_workspaces.

PATCH`/v1/workspace`

Update workspace settings (owner/admin)

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

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

Request body (JSON)
Name	Type	Required
`name`	`string`length 1–100	No
`slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	No
`portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	No

Response 200: 6 fields

Response 200 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`name`	`string`length 1–100	Yes
`slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	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/workspace' \
  -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/workspace', { body: { name: 'Example' } });

MCP

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

POST`/v1/workspace/switch`

Verify membership and return the workspace and role to switch to

Authentication: Dashboard session only (API keys get 403 session_required)
Operation id: switchWorkspace
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 200: 9 fields

Response 200 (application/json)
Name	Type	Required
`workspace`	`object`	Yes
`workspace.id`	`string (uuid)`	Yes
`workspace.name`	`string`length 1–100	Yes
`workspace.slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`workspace.portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	Yes
`workspace.created_at`	`string (date-time)`	Yes
`workspace.updated_at`	`string (date-time)`	Yes
`role`	`"owner" \| "admin" \| "member"`	Yes
`operator_id`	`string (uuid)`	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/workspace/switch' \
  -H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/workspace/switch', { body: {} });

MCP

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

GET`/v1/workspace/sso`

End-user SSO state: enabled, audience, secret dates; never the secret (owner/admin)

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

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

Response 200: 5 fields

Response 200 (application/json)
Name	Type	Required
`enabled`	`boolean`	Yes
`configured`	`boolean`	Yes
`audience`	`string (uuid)`	Yes
`secret_created_at`	`string (date-time) \| null`	Yes
`previous_secret_expires_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/workspace/sso' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

PATCH`/v1/workspace/sso`

Accept or stop accepting SSO tokens; needs a secret to enable (owner/admin)

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

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

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

Response 200: 5 fields

Response 200 (application/json)
Name	Type	Required
`enabled`	`boolean`	Yes
`configured`	`boolean`	Yes
`audience`	`string (uuid)`	Yes
`secret_created_at`	`string (date-time) \| null`	Yes
`previous_secret_expires_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 PATCH 'https://api.upvoiced.com/v1/workspace/sso' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'

TypeScript SDK

const data = await upvoiced.patch('/v1/workspace/sso', { body: { enabled: true } });

MCP

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

POST`/v1/workspace/sso/rotate`

Create or rotate the SSO secret, shown once; the old one verifies for grace_hours (owner/admin, re-auth ≤ 10 min)

Authentication: Dashboard session only (API keys get 403 session_required)
Operation id: rotateSsoSecret
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
`grace_hours`	`integer`value 0–168default 24	No

Response 200: 6 fields

Response 200 (application/json)
Name	Type	Required
`enabled`	`boolean`	Yes
`configured`	`boolean`	Yes
`audience`	`string (uuid)`	Yes
`secret_created_at`	`string (date-time) \| null`	Yes
`previous_secret_expires_at`	`string (date-time) \| null`	Yes
`secret`	`string`pattern ^uvsso_[A-Za-z0-9_-]{43}$	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/workspace/sso/rotate' \
  -H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grace_hours": 24
}'

TypeScript SDK

const data = await upvoiced.post('/v1/workspace/sso/rotate', { body: { grace_hours: 24 } });

MCP

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

GET`/v1/workspace/widget`

Widget settings: allowed origins, the always-allowed portal origin, enabled tabs, install date (any member)

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

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

Response 200: 4 fields

Response 200 (application/json)
Name	Type	Required
`allowed_origins`	`array of string`items ≤ 50	Yes
`first_party_origins`	`array of string`items ≤ 4	Yes
`tabs`	`array of "feedback" \| "roadmap" \| "whats-new"`items 1–3	Yes
`installed_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/workspace/widget' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

PATCH`/v1/workspace/widget`

Set the exact browser origins allowed on the end-user API and the enabled widget tabs (owner/admin)

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

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

Request body (JSON)
Name	Type	Required
`allowed_origins`	`array of string`items ≤ 50	No
`tabs`	`array of "feedback" \| "roadmap" \| "whats-new"`items 1–3	No

Response 200: 4 fields

Response 200 (application/json)
Name	Type	Required
`allowed_origins`	`array of string`items ≤ 50	Yes
`first_party_origins`	`array of string`items ≤ 4	Yes
`tabs`	`array of "feedback" \| "roadmap" \| "whats-new"`items 1–3	Yes
`installed_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 PATCH 'https://api.upvoiced.com/v1/workspace/widget' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed_origins": [
    "Example allowed origins"
  ]
}'

TypeScript SDK

const data = await upvoiced.patch('/v1/workspace/widget', { body: { allowed_origins: ['Example allowed origins'] } });

MCP

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

GET`/v1/workspace/deletion`

Deletion state, purge date and whether a restore is possible (owner/admin)

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

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

Response 200: 4 fields

Response 200 (application/json)
Name	Type	Required
`state`	`"active" \| "scheduled" \| "purging"`	Yes
`deleted_at`	`string (date-time) \| null`	Yes
`purge_after`	`string (date-time) \| null`	Yes
`restorable`	`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/workspace/deletion' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

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

MCP

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

POST`/v1/workspace/deletion`

Owner-only, re-authenticated soft deletion with typed slug

Authentication: Dashboard session only (API keys get 403 session_required)
Operation id: deleteWorkspace
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
`confirmation_slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes

Response 202: 2 fields

Response 202 (application/json)
Name	Type	Required
`deleted_at`	`string (date-time)`	Yes
`purge_after`	`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/workspace/deletion' \
  -H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmation_slug": "acme"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/workspace/deletion', { body: { confirmation_slug: 'acme' } });

MCP

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

POST`/v1/workspace/restore`

Restore a soft-deleted workspace within 30 days, before purge starts (owner)

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

Response 200 (application/json)
Name	Type	Required
`id`	`string (uuid)`	Yes
`name`	`string`length 1–100	Yes
`slug`	`string`length 3–32pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$	Yes
`portal_locale`	`"en" \| "pt-BR" \| "es" \| "de" \| "fr"`	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/workspace/restore' \
  -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/workspace/restore', { body: {} });

MCP

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

Workspace

GET/v1/workspaces

POST/v1/workspaces

GET/v1/workspace

PATCH/v1/workspace

POST/v1/workspace/switch

GET/v1/workspace/sso

PATCH/v1/workspace/sso

POST/v1/workspace/sso/rotate

GET/v1/workspace/widget

PATCH/v1/workspace/widget

GET/v1/workspace/deletion

POST/v1/workspace/deletion

POST/v1/workspace/restore

GET`/v1/workspaces`

POST`/v1/workspaces`

GET`/v1/workspace`

PATCH`/v1/workspace`

POST`/v1/workspace/switch`

GET`/v1/workspace/sso`

PATCH`/v1/workspace/sso`

POST`/v1/workspace/sso/rotate`

GET`/v1/workspace/widget`

PATCH`/v1/workspace/widget`

GET`/v1/workspace/deletion`

POST`/v1/workspace/deletion`

POST`/v1/workspace/restore`