​

API de Workspaces

​

Listar seus workspaces

curl "https://pilotstatus.com.br/v1/workspaces" \
  -H "x-api-key: ps_account_your_account_key"

{
  "data": [
    {
      "id": "cmh2a1b2c0001ws8example7k",
      "name": "Acme Resale",
      "role": "OWNER",
      "plan": "PAY_AS_YOU_GO",
      "createdAt": "2026-03-02T12:00:00.000Z",
      "sharedCard": { "linked": false, "sourceWorkspaceId": null }
    },
    {
      "id": "cmh2a9z8y0002ws8example1q",
      "name": "Bakery Downtown",
      "role": "OWNER",
      "plan": "PAY_AS_YOU_GO",
      "createdAt": "2026-10-28T09:15:00.000Z",
      "sharedCard": { "linked": true, "sourceWorkspaceId": "cmh2a1b2c0001ws8example7k" }
    }
  ]
}

• Só os workspaces em que a sua participação está ativa. Workspaces arquivados ficam de fora.
• role é o seu papel naquele workspace: OWNER, ADMIN, AGENT ou ANALYST.
• plan é o plano atual do workspace (FREE, PAY_AS_YOU_GO, ON_DEMAND, …).
• sharedCard diz se o workspace está vinculado a um cartão compartilhado: linked e, quando vinculado, o sourceWorkspaceId cujo cartão o cobre (null quando não está vinculado). Veja Cartão compartilhado por workspace.
• Use o id em x-workspace-id para atuar dentro daquele workspace com a mesma chave de conta.

​

Criar um workspace

curl -X POST "https://pilotstatus.com.br/v1/workspaces" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_account_your_account_key" \
  -d '{ "name": "Bakery Downtown", "shareCard": true }'

{
  "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" }
}

• apiKey.key vem só nesta resposta. Guarde-a antes de qualquer outra coisa. As leituras seguintes mostram só prefix e last4.
• apiKey pode vir null. O workspace é salvo primeiro e a chave é criada em seguida. Se a criação da chave falhar, a resposta continua sendo 201, para que uma nova tentativa não crie um segundo workspace. Gere a chave principal com POST /v1/api-keys/regenerate (chave de conta mais x-workspace-id, papel de Proprietário), ou crie uma chave com nome com POST /v1/workspaces/{id}/api-keys.
• Criar não é idempotente. Dois POSTs criam dois workspaces. Depois de um timeout, confira GET /v1/workspaces antes de tentar de novo.
• sharedCard diz como o workspace nasceu: { "linked": false, "sourceWorkspaceId": null } sem shareCard: true.
• Com shareCard: true, o cartão é conferido antes de qualquer criação. Nenhum cartão de reserva configurado para você (409 SHARED_CARD_NOT_CONFIGURED), o workspace de origem arquivado (409 SOURCE_ARCHIVED) ou você não é mais Proprietário ativo dele (409 NO_SHARED_OWNER): nenhum workspace é criado, então tentar de novo sem shareCard é seguro.

​

Como o novo workspace nasce

​

Quantos workspaces você pode ter

{
  "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
}

​

Cartão compartilhado por workspace

• Na criação: "shareCard": true no POST /v1/workspaces. Ausente ou false, o workspace não é vinculado.
• Depois: o PUT vincula e o DELETE desvincula — veja abaixo. Desvincule um cliente que parou de pagar e o seu cartão deixa de pagar as renovações desse cliente: uma renovação recusada passa a suspender só ele.

​

Vincular o cartão compartilhado

curl -X PUT "https://pilotstatus.com.br/v1/workspaces/cmh2a9z8y0002ws8example1q/shared-card" \
  -H "x-api-key: ps_account_your_account_key"

{
  "workspaceId": "cmh2a9z8y0002ws8example1q",
  "sharedCard": { "linked": true, "sourceWorkspaceId": "cmh2a1b2c0001ws8example7k" },
  "changed": true
}

• Idempotente. Já vinculado à mesma origem: 200 com "changed": false, e nada é registrado.
• O vínculo fica registrado no Histórico do workspace como Cartão de reserva vinculado. Nenhum e-mail é enviado.
• 409 SHARED_CARD_NOT_CONFIGURED — a equipe do Pilot Status não configurou um cartão de reserva para você.
• 400 SELF_SOURCE — {workspaceId} é o próprio workspace de origem.
• 409 SOURCE_ARCHIVED — o workspace de origem está arquivado.
• 409 NO_SHARED_OWNER — você não é mais Proprietário ativo do workspace de origem.

​

Desvincular o cartão compartilhado

curl -X DELETE "https://pilotstatus.com.br/v1/workspaces/cmh2a9z8y0002ws8example1q/shared-card" \
  -H "x-api-key: ps_account_your_account_key"

{
  "workspaceId": "cmh2a9z8y0002ws8example1q",
  "sharedCard": { "linked": false, "sourceWorkspaceId": null },
  "changed": true
}

• Idempotente. Não vinculado: 200 com "changed": false, e nada é registrado.
• O desvínculo fica registrado no Histórico do workspace como Cartão de reserva desvinculado. Nenhum e-mail é enviado.
• A partir daí, as cobranças do workspace usam só a carteira e o cartão dele. Se eles não cobrirem uma renovação, esse workspace é suspenso — o seu cartão não é cobrado.
• 409 NO_SHARED_OWNER — o workspace está vinculado a um workspace de origem do qual você não é Proprietário ativo. Fale com a equipe do Pilot Status.

​

Chaves do workspace

​

Listar as chaves

{
  "data": [
    {
      "id": "cmh2aa0010003ak8example4d",
      "name": "Workspace API Key",
      "prefix": "ps_workspace_",
      "last4": "3b5d",
      "isPrimary": true,
      "createdAt": "2026-10-28T09:15:00.000Z",
      "lastUsedAt": "2026-10-28T09:20:11.000Z"
    },
    {
      "id": "cmh2ab7770004ak8example9m",
      "name": "Billing integration",
      "prefix": "ps_workspace_",
      "last4": "a1c0",
      "isPrimary": false,
      "createdAt": "2026-10-28T10:02:40.000Z",
      "lastUsedAt": null
    }
  ]
}

​

Criar uma chave com nome

{
  "apiKey": {
    "id": "cmh2ab7770004ak8example9m",
    "name": "Billing integration",
    "key": "ps_workspace_4e8b0d2f6a1c3e5b7d9f0a2c4e6b8d0f1a3c5e7b9d0fa1c0",
    "prefix": "ps_workspace_",
    "last4": "a1c0",
    "isPrimary": false,
    "createdAt": "2026-10-28T10:02:40.000Z"
  }
}

​

Revogar uma chave com nome

• A chave principal não pode ser revogada (409 PRIMARY_KEY_NOT_REVOCABLE): o agente de IA do app a usa. Rotacione-a com POST /v1/api-keys/regenerate, enviando a sua chave de conta e x-workspace-id (papel de Proprietário). Só a principal muda; as chaves com nome continuam funcionando.
• Um id que não é de uma chave de workspace deste workspace recebe 404 API_KEY_NOT_FOUND. Chaves de número são gerenciadas em /v1/api-keys.

​

Erros