> ## 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. # Criar um workspace > Cria um workspace do qual o usuário da chave de conta é dono e gera a chave PRINCIPAL dele, devolvida **só nesta resposta**. O workspace de um usuário comum nasce no Free; o de um revendedor (marcado pela equipe da Pilot Status), no Pay As You Go, cobrado pela carteira, com os preços do revendedor. Cada usuário pode ser dono de até 10 workspaces por padrão (`409 WORKSPACE_LIMIT_REACHED`, com `limit`). `shareCard: true` vincula o novo workspace ao seu cartão de reserva (o cartão compartilhado cujo workspace de origem a equipe da Pilot Status configurou para você); `false` ou AUSENTE significa NÃO compartilhado. **Mudança de comportamento (29/10/2026):** antes, o workspace de um revendedor herdava o cartão de reserva automaticamente. Com `shareCard: true` o cartão é conferido primeiro e, em `409 SHARED_CARD_NOT_CONFIGURED`, `SOURCE_ARCHIVED` ou `NO_SHARED_OWNER`, nenhum workspace é criado. `name` e `shareCard` são os únicos campos aceitos. Se a chave não puder ser gerada, a resposta continua `201`, com `apiKey: null` — gere a principal com `POST /v1/api-keys/regenerate` (chave de conta + `x-workspace-id`). Não é idempotente: duas chamadas criam dois workspaces. **Requer uma chave de conta** (`ps_account_`, criada em Perfil → API). Chaves de workspace, de número e tokens OAuth/MCP recebem `403 ACCOUNT_KEY_REQUIRED`. Enviado com `Cache-Control: no-store`. > [!WARNING] > > **Isto cria um workspace de verdade**, do qual você é dono, e a resposta traz a chave principal **só esta vez**. Exige uma chave de conta (`ps_account_`). Veja [Criar workspaces](https://docs.pilotstatus.com.br/pt-BR/api/workspaces.md#criar-um-workspace). ## OpenAPI ````yaml openapi.pt.json POST /v1/workspaces openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `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: Criar um workspace description: >- Cria um workspace do qual o usuário da chave de conta é dono e gera a chave PRINCIPAL dele, devolvida **só nesta resposta**. O workspace de um usuário comum nasce no Free; o de um revendedor (marcado pela equipe da Pilot Status), no Pay As You Go, cobrado pela carteira, com os preços do revendedor. Cada usuário pode ser dono de até 10 workspaces por padrão (`409 WORKSPACE_LIMIT_REACHED`, com `limit`). `shareCard: true` vincula o novo workspace ao seu cartão de reserva (o cartão compartilhado cujo workspace de origem a equipe da Pilot Status configurou para você); `false` ou AUSENTE significa NÃO compartilhado. **Mudança de comportamento (29/10/2026):** antes, o workspace de um revendedor herdava o cartão de reserva automaticamente. Com `shareCard: true` o cartão é conferido primeiro e, em `409 SHARED_CARD_NOT_CONFIGURED`, `SOURCE_ARCHIVED` ou `NO_SHARED_OWNER`, nenhum workspace é criado. `name` e `shareCard` são os únicos campos aceitos. Se a chave não puder ser gerada, a resposta continua `201`, com `apiKey: null` — gere a principal com `POST /v1/api-keys/regenerate` (chave de conta + `x-workspace-id`). Não é idempotente: duas chamadas criam dois workspaces. **Requer uma chave de conta** (`ps_account_`, criada em Perfil → API). Chaves de workspace, de número e tokens OAuth/MCP recebem `403 ACCOUNT_KEY_REQUIRED`. Enviado com `Cache-Control: no-store`. operationId: post_workspaces requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: De 1 a 60 caracteres, sem os espaços das pontas. example: Bakery Downtown shareCard: type: boolean default: false description: >- `true` vincula o novo workspace ao seu cartão de reserva (cartão compartilhado). `false` ou ausente: não compartilhado. Precisa ser um booleano JSON (senão, `400 INVALID_SHARE_CARD`). example: true required: - name additionalProperties: false responses: '201': description: Criado — `apiKey.key` volta só esta vez 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` não é booleano), `NAME_REQUIRED` ou `NAME_TOO_LONG` (`maxLength`) — verificados nesta ordem 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: Chave de API ausente, inválida ou revogada content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid API key '403': description: >- Não é chave de conta (`ACCOUNT_KEY_REQUIRED`), não é membro ativo do workspace (`WORKSPACE_MEMBERSHIP_REQUIRED`) ou papel abaixo de 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`); com `shareCard: true`, também `SHARED_CARD_NOT_CONFIGURED`, `SOURCE_ARCHIVED` ou `NO_SHARED_OWNER`. Em todos os casos nenhum workspace é criado content: application/json: schema: type: object properties: error: type: string code: type: string limit: type: integer description: Só em `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: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.