> ## Documentation Index > Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Sub-workspace > Creates a new sub-workspace under the primary workspace that owns the API key. The sub-workspace is a full workspace (own assistants, numbers, campaigns, call history, members) that starts with zero balance or credit limit and zero concurrency; allocate to it afterwards. Every member of the primary is given inherited access to it. The first sub-workspace turns the primary into a family in individual billing mode. Create a new sub-workspace under the primary workspace that owns the API key. The sub-workspace starts empty: no balance or credit limit, no concurrency, no assistants, and no API key. ## When to use * Onboarding a new client, brand, or team that needs its own isolated assistants, numbers, and call history. * Automating tenant provisioning from your own admin system. ## Request parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------- | | `name` | string | Yes | Display name, 1 to 100 characters. Surrounding whitespace is trimmed; a blank name is rejected. | ## Integration notes * Authenticate with the **primary** workspace's API key. A sub-workspace's key returns `400`. * Store the returned `sub_workspace.id`; every allocation call needs it. * The first sub-workspace you create turns the primary into a family in **individual** billing mode. Contact Ringg support if the family should use common billing instead. * Every member of the primary automatically gets access to the new sub-workspace. * The response never contains an API key. See [Sub-workspaces](/api-reference/endpoint/sub-workspace/overview#create-an-assistant-inside-a-sub-workspace) for how to get one. ## Error responses * **400**: `Sub-workspaces cannot have their own sub-workspaces.` — the key belongs to a sub-workspace. * **401**: Invalid or missing API key. * **403**: `Sub-workspaces are not enabled for this workspace.` * **422**: Missing or blank `name`, or a name longer than 100 characters. ## Example ```bash theme={null} curl --request POST "https://prod-api.ringg.ai/ca/api/v0/workspace/sub" \ --header "X-API-KEY: $RINGG_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "Mumbai Collections" }' ``` ## After creation Give the sub-workspace capacity with [Allocate Concurrency](/api-reference/endpoint/sub-workspace/allocate-concurrency) and, in an individual family, a [credit limit](/api-reference/endpoint/sub-workspace/reallocate-credit-limits) or [balance](/api-reference/endpoint/sub-workspace/reallocate-credit-balances). Then generate its API key in the dashboard and [create an assistant](/api-reference/endpoint/assistant/create-agent) with that key. ## OpenAPI ````yaml post /workspace/sub openapi: 3.0.0 info: title: Ringg AI API Documentation description: >- This is the documentation for the Ringg AI APIs. The Ringg AI API follows RESTful principles, making it intuitive and easy to integrate with your applications. All API requests should be made to the base URL. The API accepts and returns data in JSON format. Ensure your requests include the appropriate Content-Type header for POST and PATCH requests. version: 2.0.0 servers: - url: https://prod-api.ringg.ai/ca/api/v0 security: [] tags: - name: workspace description: Endpoints for managing your workspace. - name: agent description: Endpoints for managing assistants (agents). - name: calling description: Endpoints for making and managing calls. - name: campaign description: Endpoints for managing campaigns. - name: analytics description: Endpoints for accessing call analytics and performance metrics. - name: termination description: Endpoints for terminating active calls using different methods. - name: knowledgebase description: Endpoints for managing knowledge bases. paths: /workspace/sub: post: tags: - workspace summary: Create Sub-workspace description: >- Creates a new sub-workspace under the primary workspace that owns the API key. The sub-workspace is a full workspace (own assistants, numbers, campaigns, call history, members) that starts with zero balance or credit limit and zero concurrency; allocate to it afterwards. Every member of the primary is given inherited access to it. The first sub-workspace turns the primary into a family in individual billing mode. operationId: createSubWorkspace parameters: - name: X-API-KEY in: header description: >- (Required) The API key of the PRIMARY workspace. A sub-workspace's key is refused with 400. required: true schema: type: string example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9 requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 100 description: >- (Required) Display name of the new sub-workspace, 1-100 characters. Surrounding whitespace is trimmed. example: Mumbai Collections example: name: Mumbai Collections responses: '200': description: 'Successful Response: The new sub-workspace.' content: application/json: schema: type: object properties: message: type: string example: Sub-workspace Mumbai Collections created successfully sub_workspace: type: object properties: id: type: string example: b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30 name: type: string example: Mumbai Collections parent_workspace_id: type: string example: 2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11 created_at: type: string format: date-time example: '2026-09-18T06:41:12.884312+00:00' concurrency: type: integer example: 0 limit_concurrency: type: integer example: 0 example: message: Sub-workspace Mumbai Collections created successfully sub_workspace: id: b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30 name: Mumbai Collections parent_workspace_id: 2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11 created_at: '2026-09-18T06:41:12.884312+00:00' concurrency: 0 limit_concurrency: 0 '400': description: >- Bad Request - The API key belongs to a sub-workspace (no nesting), or the name is blank. content: application/json: schema: type: object properties: detail: type: string example: Sub-workspaces cannot have their own sub-workspaces. '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: 401 Unauthorized message: type: string example: Invalid credentials '403': description: >- Forbidden - Sub-workspaces are not enabled for this workspace, or the caller is not an active member of the primary. content: application/json: schema: type: object properties: detail: type: string example: Sub-workspaces are not enabled for this workspace. '500': description: Internal Server Error - Something went wrong on our end. content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: 500 Internal Server Error message: type: string example: An unexpected error occurred on the server. ````