> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Workspace

> Read and update your workspace settings, and permanently delete a 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.

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

**Response — 200 OK**

```json
{
  "id": "ws_xyz123",
  "name": "Acme Corp",
  "tier": "builder",
  "webhook_url": "https://hooks.acme.com/voicebip",
  "retention_days": 90,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-03-20T14:32:00Z"
}
```

### Response fields

| Field            | Type           | Description                                                                                                                                                  |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | string         | Workspace ID — prefix `ws_`. Immutable.                                                                                                                      |
| `name`           | string         | Display name for the workspace.                                                                                                                              |
| `tier`           | string         | Billing tier: `starter`, `builder`, or `scale`. Controlled by the billing system — not editable here.                                                        |
| `webhook_url`    | string \| null | Workspace-level webhook URL. Stored for reference but not used by the delivery engine as a fallback — set `webhook_url` directly on each agent.              |
| `retention_days` | integer        | How long call recordings, transcripts, and message content are kept before automatic deletion. Range: 1 – 3650. See [Data Retention](#data-retention) below. |
| `created_at`     | string         | ISO 8601 UTC timestamp.                                                                                                                                      |
| `updated_at`     | string         | ISO 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.

```bash
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

| Field            | Type    | Constraints                                                    |
| ---------------- | ------- | -------------------------------------------------------------- |
| `name`           | string  | Minimum 1 character.                                           |
| `webhook_url`    | string  | Must start with `http://` or `https://`. Send `null` to clear. |
| `retention_days` | integer | 1 – 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](/reference/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.

```bash
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

| Condition                                  | Status | Error code         |
| ------------------------------------------ | ------ | ------------------ |
| `confirm` query param is absent            | 400    | `INVALID_ARGUMENT` |
| `confirm` does not match your workspace ID | 400    | `INVALID_ARGUMENT` |
| API key is missing or revoked              | 401    | `UNAUTHENTICATED`  |