Workspaces

Create and manage workspaces, request ownership transfer or deletion, and (as sub-resources) manage a workspace’s API keys and inspect its API usage and request history.

Base URL

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

Authentication: All core workspace endpoints (GET/POST/PATCH/DELETE /v1/workspaces*) require the workspaces:read / workspaces:write scopes. The API-key sub-resources below (api-keys, api-usage, request-history) have no scope of their own — see each section for its actual requirement.

List Workspaces

GET /v1/workspaces

Returns every workspace the caller is a member of.

curl https://api.voxburst.io/v1/workspaces \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Create a Workspace

POST /v1/workspaces

curl -X POST https://api.voxburst.io/v1/workspaces \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Co", "slug": "acme-co" }'

The caller becomes OWNER. Enforces the plan’s workspace-count limit — returns 403 with plan/limit details if exceeded.

Error Codes

Get a Workspace

GET /v1/workspaces/:id

curl https://api.voxburst.io/v1/workspaces/wsp_example123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Update a Workspace

PATCH /v1/workspaces/:id

All fields optional.

curl -X PATCH https://api.voxburst.io/v1/workspaces/wsp_example123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "week_start_day": "monday" } }'

Workspace Settings

The settings object is strictly typed server-side — any key not in this list is silently stripped before it reaches the database. Every currently supported key:

Error Codes

Delete a Workspace

DELETE /v1/workspaces/:id

curl -X DELETE https://api.voxburst.io/v1/workspaces/wsp_example123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Error Codes

Request Workspace Deletion

POST /v1/workspaces/:id/deletion-requests

Creates a deletion request (owner/admin only) that kicks off VoxBurst’s deletion review process, distinct from the immediate DELETE /v1/workspaces/:id above.

curl -X POST https://api.voxburst.io/v1/workspaces/wsp_example123/deletion-requests \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Consolidating into a single workspace" }'

Ownership Transfer

Transfer workspace ownership to another user. The target user must accept before ownership actually moves — nothing changes until they do.

A transfer request expires after 7 days if not accepted. Initiating a transfer checks that the target user has capacity (workspace-count limit) to become an additional owner before creating the request.

Error Codes

Workspace API Keys

/v1/workspaces/:id/api-keys

Create an API Key

POST /v1/workspaces/:id/api-keys

curl -X POST https://api.voxburst.io/v1/workspaces/wsp_example123/api-keys \
  -H "Authorization: Bearer <cognito-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI integration", "scopes": ["posts:read", "posts:write"] }'

Response (201)

{
  "data": {
    "id": "key_abc123",
    "name": "CI integration",
    "prefix": "vb_live_xxxx",
    "scopes": ["posts:read", "posts:write"],
    "createdAt": "2026-08-01T00:00:00.000Z",
    "expiresAt": null,
    "key": "vb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Workspaces are capped at 25 active keys.

List API Keys

GET /v1/workspaces/:id/api-keys — never returns the full key, only prefix. Each key includes expirationStatus ("active" | "expiring_soon" | "expired", "expiring_soon" = within 7 days) and daysUntilExpiration.

List Keys Expiring Soon

GET /v1/workspaces/:id/api-keys/expiring?days=7 — days must be 1–365 (default 7).

Update an API Key

PATCH /v1/workspaces/:id/api-keys/:keyId

Revoke an API Key

DELETE /v1/workspaces/:id/api-keys/:keyId — soft-deletes (sets revokedAt); does not hard-delete the row.

Per-Key Usage

GET /v1/workspaces/:id/api-keys/:keyId/usage?startDate=&endDate=

Returns total request count, last-used timestamp, per-endpoint breakdown (method, path, count, error count), and average response time for a single key. Defaults to the current calendar month if no date range is given.

Error Codes (all API key endpoints)

Workspace API Usage

GET /v1/workspaces/:id/api-usage

Returns aggregate API request counts against the workspace’s monthly plan limit for the current billing period.

curl https://api.voxburst.io/v1/workspaces/wsp_example123/api-usage \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

{
  "data": {
    "requests": { "total": 4213, "limit": 100000, "remaining": 95787 },
    "percentage": { "remaining": 96, "used": 4 },
    "status": "healthy",
    "period": { "start": "2026-08-01T00:00:00.000Z", "end": "2026-08-31T23:59:59.000Z" },
    "plan": { "slug": "pro", "name": "Pro" }
  }
}

status is "healthy" below 75% used, "warning" at 75–89%, "critical" at 90%+.

Additional Usage Breakdown Endpoints

Request History

GET /v1/workspaces/:id/request-history

Developer-friendly, paginated log of API requests made against the workspace — built for debugging integrations. Rate limited to 30 requests/minute.

Query Parameters

curl "https://api.voxburst.io/v1/workspaces/wsp_example123/request-history?status=500&limit=20" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "log_abc123",
      "timestamp": "2026-08-30T12:00:00.000Z",
      "method": "POST",
      "path": "/v1/posts",
      "statusCode": 201,
      "responseTimeMs": 142,
      "requestId": "req_xyz789",
      "apiKeyId": "key_abc123",
      "actorType": "api_key",
      "actorId": null,
      "ipAddress": "203.0.113.4"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "eyJ...", "limit": 20 }
}