> ## 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. # Create a sub-workspace > Creates a workspace under this API key's workspace (its *parent*). Every workspace created through the API is a sub-workspace of the key's workspace; there is no way to create a workspace without a parent, and the parent is not a request field. - Only Enterprise workspaces can create sub-workspaces, and a sub-workspace's key cannot (`403 permission_denied`). - A new sub-workspace is on the Starter plan and starts setting itself up right away (`provisioning.status`). - Every admin of the parent workspace is an admin of the sub-workspace. `admin_emails` also get an email invite to join it as admins. - `billed_to: parent` means the sub-workspace is paid while the parent's subscription is; `self` means it is billed on its own. - Send `external_id` (your own reference for the workspace) to make retries safe: a create with an `external_id` already used under this parent returns that workspace with `200` when `name`, `domain` and `billed_to` match, and `409 workspace_exists` when they do not. - Each parent can create a limited number of sub-workspaces per hour (`429 rate_limited` with `Retry-After`). ## OpenAPI ````yaml /api-reference/openapi.yaml post /workspaces openapi: 3.1.0 info: title: Avina API version: 1.0.0-draft description: > The Avina developer API, for calling Avina from your own servers. **Authentication.** Send your workspace API key: `Authorization: Bearer `. Create keys in the Avina dashboard under Settings → API keys. **Credits.** `GET /usage` reports your workspace's signal credits for the current billing period: the same credits and period the dashboard shows. **Conventions.** JSON with snake_case fields and UTC ISO-8601 timestamps. Paginated lists use `limit` + `after` cursor pagination. `POST` requests accept an `Idempotency-Key` header (kept 24 hours). Every response has `X-Request-Id`. Request bodies must be JSON (`415 invalid_request` otherwise) and are limited to 100 KB (`413 invalid_request`). A `503 internal_error` means the API key could not be checked; retry the request. servers: - url: https://api.avina.io/v1 description: Production (proposed domain) security: - apiKey: [] tags: - name: Account - name: Personas - name: Workspaces paths: /workspaces: post: tags: - Workspaces summary: Create a sub-workspace description: > Creates a workspace under this API key's workspace (its *parent*). Every workspace created through the API is a sub-workspace of the key's workspace; there is no way to create a workspace without a parent, and the parent is not a request field. - Only Enterprise workspaces can create sub-workspaces, and a sub-workspace's key cannot (`403 permission_denied`). - A new sub-workspace is on the Starter plan and starts setting itself up right away (`provisioning.status`). - Every admin of the parent workspace is an admin of the sub-workspace. `admin_emails` also get an email invite to join it as admins. - `billed_to: parent` means the sub-workspace is paid while the parent's subscription is; `self` means it is billed on its own. - Send `external_id` (your own reference for the workspace) to make retries safe: a create with an `external_id` already used under this parent returns that workspace with `200` when `name`, `domain` and `billed_to` match, and `409 workspace_exists` when they do not. - Each parent can create a limited number of sub-workspaces per hour (`429 rate_limited` with `Retry-After`). operationId: createWorkspace parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspaceCreate' example: name: Acme West domain: https://www.acmewest.com external_id: crm-account-4821 billed_to: parent admin_emails: - owner@acmewest.com responses: '200': description: >- The sub-workspace already created with this `external_id`; nothing new was created and no invites were sent (`invited_admins` is empty). content: application/json: schema: $ref: '#/components/schemas/Workspace' '201': description: The created sub-workspace. content: application/json: schema: $ref: '#/components/schemas/Workspace' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/WorkspaceConflict' '429': $ref: '#/components/responses/WorkspaceRateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Any unique string. Retrying with the same key returns the first response instead of repeating the action. schema: type: string maxLength: 255 schemas: WorkspaceCreate: type: object additionalProperties: false required: - name - domain properties: name: type: string minLength: 1 maxLength: 100 domain: type: string description: >- The company's website or domain (`https://www.acme.com/about` or `acme.com`). Stored and returned as the bare domain (`acme.com`). external_id: type: string minLength: 1 maxLength: 191 description: >- Your own reference for this workspace, unique among this workspace's sub-workspaces. Repeating a create with it returns the existing workspace. Matching ignores case (`CRM-42` and `crm-42` are the same `external_id`). billed_to: type: string enum: - parent - self default: parent description: >- `parent`: the sub-workspace is paid while the parent's subscription is. `self`: it is billed on its own. admin_emails: type: array maxItems: 10 items: type: string format: email maxLength: 191 description: >- Each gets an email invite to join the sub-workspace as an admin. Duplicates (ignoring case) are invited once. The parent's admins are admins already and need no invite. Workspace: type: object required: - object - id - name - domain - external_id - billed_to - parent_workspace - created_at - provisioning properties: object: type: string const: workspace id: type: string format: uuid name: type: string domain: type: - string - 'null' external_id: type: - string - 'null' billed_to: type: string enum: - parent - self parent_workspace: type: object required: - name properties: name: type: string created_at: type: string format: date-time provisioning: type: object required: - status properties: status: type: string enum: - not_started - in_progress - completed description: >- Setting up the workspace's data takes a while after it is created. `not_started` means setup has not started yet; for a workspace created through the API, it starts again when the create is repeated with the same `external_id`. A workspace Avina staff placed under this workspace is `completed` once its own setup finished. invited_admins: type: array items: type: string description: >- Only in the `POST /workspaces` response. The `admin_emails` invited by that request (empty when the request returned an existing workspace). An email that is already a member of the workspace is not invited. example: object: workspace id: 3f2b8a52-7c1e-4d7a-9a51-2d8f0e6c4b10 name: Acme West domain: acmewest.com external_id: crm-account-4821 billed_to: parent parent_workspace: name: Acme created_at: '2026-10-13T17:02:11Z' provisioning: status: in_progress invited_admins: - owner@acmewest.com Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - invalid_request - invalid_api_key - permission_denied - not_found - workspace_exists - idempotency_key_reused - rate_limited - internal_error - timeout message: type: string request_id: type: string details: type: array items: type: object properties: field: type: string message: type: string responses: BadRequest: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: foo is not a recognized field request_id: req_8f2a details: - field: foo message: is not a recognized field Unauthorized: description: The API key is missing, invalid or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: The API key is invalid or revoked. request_id: req_8f2a Forbidden: description: This API key's workspace may not do this. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: permission_denied message: Only Enterprise workspaces can create sub-workspaces. request_id: req_8f2a WorkspaceConflict: description: > `workspace_exists`: the `external_id` already belongs to a sub-workspace with a different `name`, `domain` or `billed_to`. `idempotency_key_reused`: the idempotency key was reused with a different body, or its first request is still running. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: workspace_exists message: >- A workspace with this external_id already exists with a different name, domain or billed_to. request_id: req_8f2a details: - field: external_id message: is used by a workspace with different fields WorkspaceRateLimited: description: > Too many requests (retry after `RateLimit-Reset` seconds), or this workspace has created as many sub-workspaces as it may this hour (retry after `Retry-After` seconds). headers: Retry-After: schema: type: integer description: Seconds until the hourly sub-workspace limit resets. RateLimit-Limit: schema: type: integer RateLimit-Remaining: schema: type: integer RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: >- This workspace has reached its hourly limit for creating workspaces. Retry after Retry-After seconds. request_id: req_8f2a securitySchemes: apiKey: type: http scheme: bearer description: Workspace API key from the Avina dashboard (Settings → API keys). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.