Skip to content
UpVoiced Docs

API reference

Media uploads

Pre-signed uploads for post images and changelog media.

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.

POST/v1/media/presign

Presign a bounded R2 upload (logo → branding bucket, image → media bucket)

Authentication
API key or Dashboard session; API key scope write
Operation id
presignMedia
Idempotency
Send an Idempotency-Key to make retries safe.
Headers
NameTypeRequired
x-workspacestring (uuid)Yes
idempotency-keystringpattern ^[A-Za-z0-9_.:-]{8,128}$No
Response 201: 8 fields
Response 201 (application/json)
NameTypeRequired
idstring (uuid)Yes
method"PUT"Yes
upload_urlstring (uri)Yes
expires_atstring (date-time)Yes
headersobjectYes
headers.content-type"image/png" | "image/jpeg" | "image/webp"Yes
headers.content-lengthstringpattern ^[1-9][0-9]*$Yes
headers.if-none-match"*"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/media/presign' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "logo",
  "mime": "image/png",
  "bytes": 1
}'
TypeScript SDK
const data = await upvoiced.post('/v1/media/presign', { body: { kind: 'logo', mime: 'image/png', bytes: 1 } });
MCP

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

POST/v1/media/{id}/complete

Verify the uploaded size, type and magic bytes, then mark ready

Authentication
API key or Dashboard session; API key scope write
Operation id
completeMedia
Idempotency
Send an Idempotency-Key to make retries safe.
Path parameters
NameTypeRequired
idstring (uuid)Yes
Headers
NameTypeRequired
x-workspacestring (uuid)Yes
idempotency-keystringpattern ^[A-Za-z0-9_.:-]{8,128}$No
Response 200: 2 fields
Response 200 (application/json)
NameTypeRequired
idstring (uuid)Yes
status"ready"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/media/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d/complete' \
  -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/media/{id}/complete', {
  path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' },
  body: {},
});
MCP

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