Skip to main content
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.
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

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:
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.