> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create a workspace > Creates a workspace owned by the account key's user and mints its PRIMARY workspace key, returned **only in this response**. A regular user's workspace is born on Free; a reseller's (marked by the Pilot Status team) on Pay As You Go, billed from the wallet, with the reseller's prices. Each user owns up to 10 workspaces by default (`409 WORKSPACE_LIMIT_REACHED`, with `limit`). `shareCard: true` links the new workspace to your reserve card (the shared card whose source workspace the Pilot Status team configured for you); `false` or ABSENT means NOT shared. **Behavior change (2026-10-29):** before, a reseller's workspace inherited the reserve card automatically. With `shareCard: true` the card is checked first and, on `409 SHARED_CARD_NOT_CONFIGURED`, `SOURCE_ARCHIVED` or `NO_SHARED_OWNER`, no workspace is created. `name` and `shareCard` are the only accepted fields. If the key cannot be minted the answer is still `201` with `apiKey: null` — rotate the primary with `POST /v1/api-keys/regenerate` (account key + `x-workspace-id`). Not idempotent: two calls create two workspaces. **Requires an account key** (`ps_account_`, created in Profile → API). Workspace keys, number keys and OAuth/MCP tokens get `403 ACCOUNT_KEY_REQUIRED`. Sent with `Cache-Control: no-store`. > [!WARNING] > > **This creates a real workspace** owned by you, and the response carries its primary key **only this once**. Requires an account key (`ps_account_`). See [Create workspaces](https://docs.pilotstatus.com.br/api/workspaces.md#create-a-workspace). ## OpenAPI ````yaml openapi.json POST /v1/workspaces openapi: 3.1.0 info: title: Pilot Status API version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- Public REST API for Pilot Status. Authenticate with the `x-api-key: ps_...` header (or `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/workspaces: post: tags: - Workspace summary: Create a workspace description: >- Creates a workspace owned by the account key's user and mints its PRIMARY workspace key, returned **only in this response**. A regular user's workspace is born on Free; a reseller's (marked by the Pilot Status team) on Pay As You Go, billed from the wallet, with the reseller's prices. Each user owns up to 10 workspaces by default (`409 WORKSPACE_LIMIT_REACHED`, with `limit`). `shareCard: true` links the new workspace to your reserve card (the shared card whose source workspace the Pilot Status team configured for you); `false` or ABSENT means NOT shared. **Behavior change (2026-10-29):** before, a reseller's workspace inherited the reserve card automatically. With `shareCard: true` the card is checked first and, on `409 SHARED_CARD_NOT_CONFIGURED`, `SOURCE_ARCHIVED` or `NO_SHARED_OWNER`, no workspace is created. `name` and `shareCard` are the only accepted fields. If the key cannot be minted the answer is still `201` with `apiKey: null` — rotate the primary with `POST /v1/api-keys/regenerate` (account key + `x-workspace-id`). Not idempotent: two calls create two workspaces. **Requires an account key** (`ps_account_`, created in Profile → API). Workspace keys, number keys and OAuth/MCP tokens get `403 ACCOUNT_KEY_REQUIRED`. Sent with `Cache-Control: no-store`. operationId: post_workspaces requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: 1 to 60 characters, after trimming. example: Bakery Downtown shareCard: type: boolean default: false description: >- `true` links the new workspace to your reserve card (shared card). `false` or absent: not shared. Must be a JSON boolean (`400 INVALID_SHARE_CARD` otherwise). example: true required: - name additionalProperties: false responses: '201': description: Created — `apiKey.key` is returned only this once content: application/json: example: id: cmh2a9z8y0002ws8example1q name: Bakery Downtown plan: PAY_AS_YOU_GO createdAt: '2026-10-28T09:15:00.000Z' role: OWNER apiKey: id: cmh2aa0010003ak8example4d name: Workspace API Key key: >- ps_workspace_9f3c1a7e5b2d8f4a6c0e9b1d7f3a5c8e2b4d6f8a0c1e3b5d prefix: ps_workspace_ last4: 3b5d isPrimary: true createdAt: '2026-10-28T09:15:00.000Z' sharedCard: linked: true sourceWorkspaceId: cmh2a1b2c0001ws8example7k headers: Cache-Control: schema: type: string example: no-store '400': description: >- `UNKNOWN_FIELDS` (`unknownFields`), `INVALID_SHARE_CARD` (`shareCard` not a boolean), `NAME_REQUIRED` or `NAME_TOO_LONG` (`maxLength`) — checked in this order content: application/json: schema: type: object properties: error: type: string code: type: string example: error: The name is required | O nome é obrigatório code: NAME_REQUIRED '401': description: Missing, invalid or revoked API key content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid API key '403': description: >- Not an account key (`ACCOUNT_KEY_REQUIRED`), not an active member of the workspace (`WORKSPACE_MEMBERSHIP_REQUIRED`), or a role below Admin (`PERMISSION_DENIED`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- This endpoint requires an account API key (ps_account_…), created in Profile → API. Workspace keys, number keys and OAuth tokens cannot use it | Este endpoint exige uma API key de conta (ps_account_…), criada em Perfil → API. Chaves de workspace, de número e tokens OAuth não podem usá-lo code: ACCOUNT_KEY_REQUIRED '409': description: >- `WORKSPACE_LIMIT_REACHED` (`limit`); with `shareCard: true`, also `SHARED_CARD_NOT_CONFIGURED`, `SOURCE_ARCHIVED` or `NO_SHARED_OWNER`. In every case no workspace is created content: application/json: schema: type: object properties: error: type: string code: type: string limit: type: integer description: Only on `WORKSPACE_LIMIT_REACHED`. example: error: >- You already own 10 workspaces, which is the limit | Você já é dono de 10 workspaces, que é o limite code: WORKSPACE_LIMIT_REACHED limit: 10 components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your ps_ API key apiKeyId: type: apiKey in: header name: x-api-key-id description: API key id (alternative to x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.