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

# Sub-workspaces

> Create and track workspaces under your own, for example one per client.

A sub-workspace is a separate Avina workspace that belongs to your workspace (its *parent*). Agencies and resellers use them to run Avina for each client: every sub-workspace has its own signals, personas, credits and team, and your workspace's admins can open all of them.

> [!NOTE]
>
> Only Enterprise workspaces can create sub-workspaces. A sub-workspace's own API key cannot create sub-workspaces, so they are one level deep. Other workspaces get `403 permission_denied`.

## What a new sub-workspace gets

* **Plan:** it starts on the Starter plan, with its own Starter credits.
* **Admins:** every admin of your workspace is an admin of each sub-workspace. This follows your workspace: when someone becomes an admin or stops being one in your workspace, the same happens in every sub-workspace. Their access can only be changed in your workspace, not in the sub-workspace.
* **Invites:** each address in `admin_emails` (up to 10) gets an email invite to join the sub-workspace as an admin. An invite expires after 48 hours, and the API cannot send it again.
* **Billing:** with `billed_to: "parent"` (the default), the sub-workspace is paid for by your workspace: it is active while your subscription is. With `"self"`, it is billed on its own.
* **Setup:** Avina sets up the workspace's data after it is created, which takes a while. `provisioning.status` goes from `in_progress` to `completed`.

## Create one

```bash theme={null}
curl -X POST https://api.avina.io/v1/workspaces \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme West",
    "domain": "https://www.acmewest.com",
    "external_id": "crm-account-4821",
    "billed_to": "parent",
    "admin_emails": ["owner@acmewest.com"]
  }'
```

`domain` is the client's website or domain. It is stored and returned as the bare domain (`acmewest.com`).

The response is the new workspace with `201`, including `invited_admins`, the addresses that were invited.

## Retry safely with `external_id`

`external_id` is your own reference for the workspace, such as a CRM account id. It is unique among your sub-workspaces, and matching ignores case (`CRM-42` and `crm-42` are the same).

* Repeating a create with an `external_id` you already used, and the same `name`, `domain` and `billed_to`, returns that workspace with `200`. Nothing new is created and no invites are sent (`invited_admins` is empty).
* The same `external_id` with a different `name`, `domain` or `billed_to` returns `409 workspace_exists`.

Send `external_id` on every create. An `Idempotency-Key` only covers a retry with the same key, while `external_id` also protects a retry that uses a new key or comes from another process.

## Track setup

Read the workspace until `provisioning.status` is `completed`:

```bash theme={null}
curl https://api.avina.io/v1/workspaces/$WORKSPACE_ID \
  -H "Authorization: Bearer $AVINA_API_KEY"
```

| `provisioning.status` | Meaning |
| - | - |
| `in_progress` | Setup is running. |
| `completed` | The workspace is ready. |
| `not_started` | Setup could not start. Repeat the create with the same `external_id` to start it again. |

`GET /workspaces` lists your sub-workspaces newest first, with `limit` and `after` cursor pagination. It also lists workspaces Avina placed under yours, which usually have no `external_id`.

## Limits

* Each workspace can create 10 sub-workspaces per hour. Past that, a create returns `429 rate_limited` with a `Retry-After` header: the seconds until you can create more. Repeating a create with an `external_id` you already used does not count.
* `GET /workspaces/{workspace_id}` returns `404 not_found` for any id that is not one of your sub-workspaces, including your own workspace's id.
* If setup shows `not_started` and the workspace was created without an `external_id`, the API cannot restart it; contact support with the workspace id.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.