Skip to Content
API ReferenceUsers

Users

Manage the authenticated user’s own profile. Every endpoint in this group operates on “me” — there is no way to look up another user by ID through this API.

All /v1/users routes require a Cognito session — API keys cannot call this group. API keys are workspace-scoped credentials with no associated user identity, so there is no “current user” for an API key request. Use a Cognito access or ID token. See Cognito Session (JWT) Authentication.

Base URL

https://api.voxburst.io/v1/users

Get Current User Profile

GET /v1/users/me

curl https://api.voxburst.io/v1/users/me \
  -H "Authorization: Bearer <cognito-token>"

Response

{
  "id": "usr_example456",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "avatarUrl": "https://cdn.voxburst.io/avatars/user/usr_example456/1.png",
  "externalId": "a1b2c3d4-cognito-sub",
  "createdAt": "2026-01-15T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z",
  "isSystemAdmin": false,
  "workspaces": [
    {
      "id": "wsp_example123",
      "name": "Acme Co",
      "slug": "acme-co",
      "logo": null,
      "plan": "pro",
      "logoUrl": null,
      "role": "OWNER",
      "joinedAt": "2026-01-15T00:00:00.000Z"
    }
  ]
}

Response Fields

FieldTypeDescription
idstringUser’s VoxBurst ID
emailstringUser’s email
namestring | nullDisplay name
avatarUrlstring | nullAvatar image URL
externalIdstringCognito sub
isSystemAdminbooleanWhether the user holds an active SYSTEM_ADMIN global role
workspacesobject[]Every workspace the user is a member of, with their role in each. If the user is OWNER of a workspace, plan reflects their effective owned-plan entitlement (which can differ from the workspace’s stored plan — see Billing), not the raw stored value.

Update Current User Profile

PATCH /v1/users/me

All fields optional — send only what you want to change.

FieldTypeRequiredDescription
namestringNo1–100 characters
avatarUrlstring | nullNoMust be hosted on a trusted VoxBurst domain (*.cloudfront.net, *.amazonaws.com, *.voxburst.io, or voxburst.io). Get this URL from POST /v1/uploads/avatar-url.
curl -X PATCH https://api.voxburst.io/v1/users/me \
  -H "Authorization: Bearer <cognito-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane R. Doe" }'

Error Codes

StatusCause
400avatarUrl is not hosted on a trusted VoxBurst domain, or another field failed validation

Delete Current User Account

DELETE /v1/users/me

Deletes the account. Workspace memberships cascade-delete with it.

curl -X DELETE https://api.voxburst.io/v1/users/me \
  -H "Authorization: Bearer <cognito-token>"

Error Codes

StatusCodeCause
400—Caller is a system admin (system admin accounts cannot self-delete)
409SOLE_WORKSPACE_OWNERCaller is the sole OWNER of one or more workspaces. Response includes the affected workspaces array and a transferOwnershipUrl pattern. Transfer ownership or delete those workspaces first.

List Current User’s Workspaces

GET /v1/users/me/workspaces

Similar to the workspaces array on GET /v1/users/me, but includes member/account/post counts per workspace and no isSystemAdmin field.

curl https://api.voxburst.io/v1/users/me/workspaces \
  -H "Authorization: Bearer <cognito-token>"

Response

{
  "data": [
    {
      "id": "wsp_example123",
      "name": "Acme Co",
      "slug": "acme-co",
      "logo": null,
      "logoUrl": null,
      "plan": "pro",
      "role": "OWNER",
      "settings": {},
      "joinedAt": "2026-01-15T00:00:00.000Z",
      "memberCount": 3,
      "accountCount": 8,
      "postCount": 214
    }
  ],
  "total": 1
}

Create a Workspace for the Current User

POST /v1/users/me/workspaces

FieldTypeRequiredDescription
namestringYes2–100 characters
slugstringYes2–50 characters, lowercase alphanumeric with hyphens, must be unique
logostringNoMust be a trusted VoxBurst-hosted URL (see above)
curl -X POST https://api.voxburst.io/v1/users/me/workspaces \
  -H "Authorization: Bearer <cognito-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Second Brand", "slug": "second-brand" }'

The caller becomes OWNER of the new workspace.

Error Codes

StatusCodeCause
403LIMIT_REACHEDCaller already owns the maximum number of workspaces (3) allowed on their plan
400—slug already taken, or another field failed validation

Export Personal Data (GDPR)

GET /v1/users/me/export

Returns a JSON file containing the personal data VoxBurst holds for the user: profile, notification preferences, workspace memberships, posts the user created, connected social accounts (no tokens/credentials), and personas. Rate limited to 1 request per hour per user.

curl https://api.voxburst.io/v1/users/me/export \
  -H "Authorization: Bearer <cognito-token>" \
  -o voxburst-data-export.json

The response is returned with Content-Disposition: attachment so browser clients trigger a file download.

Error Codes

StatusCause
429Export requested more than once in the past hour. Retry-After header indicates when to retry.

Store GA4 Client ID

POST /v1/users/me/ga4-client-id

Internal analytics-stitching endpoint used by the VoxBurst dashboard to associate a browser GA4 client ID with the authenticated user for server-side event attribution.

curl -X POST https://api.voxburst.io/v1/users/me/ga4-client-id \
  -H "Authorization: Bearer <cognito-token>" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "1234567890.1234567890" }'

clientId must match the GA4 client ID format (\d+\.\d+).

Error Codes

StatusCause
400clientId is missing or does not match the required format
Last updated on
UploadsVersioning & Compatibility