> ## Documentation Index
> Fetch the complete documentation index at: https://docs.miraiminds.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces & organizations

> Onboard a workspace, archive and unarchive organizations and workspaces.

<Note>
  **This documents the v1 product.** It is kept for integrations already running
  on it. If you are building something new, start with the
  [Quickstart](/v2/quickstart).
</Note>

A **workspace** holds assistants and telephony numbers and belongs to an
**organization**. The workspace `_id` you get here is the `workspace` header
value for every workspace-scoped call afterwards.

## Onboard a custom workspace

```http theme={null}
POST /v2/workspace/onboard/custom
```

The recommended path for every non-Shopify integration.

| Field                                   | Type      | Required | Description                                     |
| :-------------------------------------- | :-------- | :------- | :---------------------------------------------- |
| `name`                                  | string    | yes      | Display name; a unique slug is derived from it. |
| `currencyCode`                          | string(3) | yes      | ISO 4217, uppercased. `INR`, `USD`.             |
| `timezone`                              | string    | yes      | IANA identifier, e.g. `Asia/Kolkata`.           |
| `supportContacts.phoneNumber`           | string    | yes      | E.164.                                          |
| `supportContacts.email`                 | string    | no       |                                                 |
| `trustSignals.valuePropositionOneLiner` | string    | yes      | One line used to ground the assistant.          |

```bash theme={null}
curl -X POST https://api.voice-agents.miraiminds.co/v2/workspace/onboard/custom \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Support Line",
    "currencyCode": "INR",
    "timezone": "Asia/Kolkata",
    "supportContacts": { "phoneNumber": "+919876543210", "email": "support@acme.com" },
    "trustSignals": { "valuePropositionOneLiner": "Premium 24x7 support for Acme customers." }
  }'
```

```json title="200 OK" theme={null}
{
  "message": "Workspace onboarded successfully.",
  "data": {
    "_id": "6690a1b2c3d4e5f600000002",
    "name": "Acme Support Line",
    "variant": "custom"
  }
}
```

Keep `data._id` — it is your `workspace` header from now on.

<Tip>
  **Auto-assigned number**

  In production a default telephony number is assigned to every new workspace.
  List it through the [Telephony](/v1/telephony) APIs before buying another.
</Tip>

| Status | Cause                                                  |
| :----- | :----------------------------------------------------- |
| `400`  | Validation error, or the organization is archived      |
| `403`  | Stand-alone organizations cannot create new workspaces |
| `409`  | A workspace with this name already exists              |

## Onboard a Shopify store

```http theme={null}
POST /v2/workspace/onboard/shopify
```

Shopify merchants only — creates the workspace and configures billing in one
step. Returns `201` with `workspace`, `status` and a `billing` block:

```json title="201 Created" theme={null}
{
  "workspace": "6690a1b2c3d4e5f600000002",
  "status": "active",
  "billing": {
    "type": "prepaid",
    "creditBalance": 100,
    "negativeCreditAllowance": 100
  }
}
```

`negativeCreditAllowance` is an overdraft: calls keep running that far past zero
before the workspace is suspended.

## Archive

```http theme={null}
POST /v1/admin/organization/archive
```

Requires an `admin` or `organization_admin` role.

```bash theme={null}
curl -X POST https://api.voice-agents.miraiminds.co/v1/admin/organization/archive \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "type": "workspace", "id": "6690a1b2c3d4e5f600000002" }'
```

| Field  | Values                        |
| :----- | :---------------------------- |
| `type` | `organization` \| `workspace` |
| `id`   | ObjectId of the target        |

```json title="200 OK" theme={null}
{ "status_code": 200, "message": "Workspace archived successfully.", "data": null }
```

Archiving **cascades**: archiving an organization archives its workspaces,
assistants and campaigns; archiving a workspace archives its assistants and
campaigns. Archived assistants cannot be updated (`400`) and cannot place calls.

## Unarchive

```http theme={null}
POST /v1/admin/organization/unarchive
```

Same body. Unarchiving also cascades. A workspace cannot be unarchived while its
parent organization is still archived:

```json title="400 Bad Request" theme={null}
{ "code": 400, "message": "Cannot unarchive workspace. Parent Organization is archived." }
```

Unarchive the organization first.