Guides

Workspace

Your workspace is the top-level container for all your agents, phone numbers, API keys, calls, and messages. The workspace API lets you read current settings, update mutable fields, and — when needed — permanently delete the workspace and all its data.

Get Workspace

Returns metadata for the workspace that owns the API key used in the request. The signing secret is never included in the response.

$curl "https://api.voicebip.com/v1/workspace" \
>  -H "Authorization: Bearer pk_live_your_key"

Response — 200 OK

1{
2  "id": "ws_xyz123",
3  "name": "Acme Corp",
4  "tier": "builder",
5  "webhook_url": "https://hooks.acme.com/voicebip",
6  "retention_days": 90,
7  "created_at": "2025-01-15T10:00:00Z",
8  "updated_at": "2025-03-20T14:32:00Z"
9}

Response fields

FieldTypeDescription
idstringWorkspace ID — prefix ws_. Immutable.
namestringDisplay name for the workspace.
tierstringBilling tier: starter, builder, or scale. Controlled by the billing system — not editable here.
webhook_urlstring | nullWorkspace-level webhook URL. Stored for reference but not used by the delivery engine as a fallback — set webhook_url directly on each agent.
retention_daysintegerHow long call recordings, transcripts, and message content are kept before automatic deletion. Range: 1 – 3650. See Data Retention below.
created_atstringISO 8601 UTC timestamp.
updated_atstringISO 8601 UTC timestamp.

Update Workspace

PATCH /v1/workspace performs a partial update — only the fields you include in the request body are changed.

tier and signing_secret cannot be updated through this endpoint. Tier changes go through PATCH /v1/workspace/subscription. Signing secret rotation has its own dedicated flow.

$curl -X PATCH "https://api.voicebip.com/v1/workspace" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Acme Fintech",
>    "webhook_url": "https://hooks.acme.com/voicebip-v2",
>    "retention_days": 180
>  }'

Returns the full updated workspace object with the same shape as the GET response.

Updatable fields

FieldTypeConstraints
namestringMinimum 1 character.
webhook_urlstringMust start with http:// or https://. Send null to clear.
retention_daysinteger1 – 3650.

Data Retention

retention_days sets the NDPR data-retention window for the entire workspace. After the window elapses, call recordings and transcripts are permanently deleted. The default at workspace creation is set by your plan.

Shorter windows reduce storage costs and limit personal-data exposure. 90 days is a common starting point for Nigerian fintechs operating under NDPR. See Best Practices for the compliance context.

Delete Workspace

Permanently deletes your workspace and cascades to all dependent records: agents, phone numbers, API keys, calls, messages, and billing history. There is no undo.

The request requires a ?confirm={workspace_id} query parameter that must exactly match your workspace ID. Omitting it or supplying a different value returns 400 INVALID_ARGUMENT before any deletion takes place.

Before deleting:

  • Export any call recordings or transcripts you need.
  • Release or port any phone numbers you want to keep.
  • Revoke or note down any downstream integrations pointing at your webhook URL.
$curl -X DELETE "https://api.voicebip.com/v1/workspace?confirm=ws_xyz123" \
>  -H "Authorization: Bearer pk_live_your_key"

Response — 204 No Content (empty body on success)

Error cases

ConditionStatusError code
confirm query param is absent400INVALID_ARGUMENT
confirm does not match your workspace ID400INVALID_ARGUMENT
API key is missing or revoked401UNAUTHENTICATED