Workspaces API

These endpoints work at the level of your user, not of one workspace. They answer only to an account key (ps_account_, created in Profile → API).

Method	Endpoint	What it does
`GET`	`/v1/workspaces`	The workspaces you are an active member of, with your role in each.
`POST`	`/v1/workspaces`	Creates a workspace that you own, with its primary key.
`GET`	`/v1/workspaces/{workspaceId}/api-keys`	The workspace’s keys (primary and named), masked.
`POST`	`/v1/workspaces/{workspaceId}/api-keys`	Creates a named workspace key.
`DELETE`	`/v1/workspaces/{workspaceId}/api-keys/{keyId}`	Revokes a named workspace key.
`PUT`	`/v1/workspaces/{workspaceId}/shared-card`	Links your reserve card (shared card) to the workspace.
`DELETE`	`/v1/workspaces/{workspaceId}/shared-card`	Unlinks your reserve card from the workspace.

Only account keys. A workspace key, a number key or an OAuth/MCP token gets 403 ACCOUNT_KEY_REQUIRED. OAuth/MCP tokens are refused on purpose: these endpoints mint keys, and a key minted through a connector would keep working after the connector is revoked. x-workspace-id is ignored here: the workspace, when there is one, is in the path.

Every response is sent with Cache-Control: no-store. Errors are { "error": "English | Português", "code": "…" }.

List your workspaces

GET https://pilotstatus.com.br/v1/workspaces

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

Response (200)

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

Only workspaces where your membership is active. Archived workspaces are left out.
role is your role in that workspace: OWNER, ADMIN, AGENT or ANALYST.
plan is the workspace’s current plan (FREE, PAY_AS_YOU_GO, ON_DEMAND, …).
sharedCard says whether the workspace is linked to a shared card: linked and, when linked, the sourceWorkspaceId whose card backs it (null when not linked). See Shared card per workspace.
Use the id in x-workspace-id to act inside that workspace with the same account key.

Create a workspace

POST https://pilotstatus.com.br/v1/workspaces with { "name": "…" } and, optionally, "shareCard": true. You become the workspace’s Owner, and the response carries its primary key, shown this one time only.

string

required

1 to 60 characters, after trimming spaces.

true links the new workspace to your reserve card (the shared card), so it backs this customer’s renewals. false or absent: the workspace is not shared. Must be a JSON boolean: "true", 1 or null get 400 INVALID_SHARE_CARD.

name and shareCard are the only fields accepted. Any other field gets 400 UNKNOWN_FIELDS.

Behavior change (2026-10-29): the reserve card is no longer shared automatically. Before, a workspace a reseller created through POST /v1/workspaces inherited the reserve card on its own. Now it is shared only when you send "shareCard": true. If your integration counted on the old behavior, add the field, or link existing workspaces with PUT …/shared-card.

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 comes only in this response. Store it before doing anything else. Later reads show only prefix and last4.
apiKey can be null. The workspace is saved first and the key is minted next. If minting fails, the answer is still 201, so that a retry does not create a second workspace. Rotate the primary key with POST /v1/api-keys/regenerate (account key plus x-workspace-id, Owner role), or create a named key with POST /v1/workspaces/{id}/api-keys.
Creating is not idempotent. Two POSTs create two workspaces. After a timeout, check GET /v1/workspaces before trying again.
sharedCard tells you how the workspace was born: { "linked": false, "sourceWorkspaceId": null } without shareCard: true.
With shareCard: true, the card is checked before anything is created. No reserve card configured for you (409 SHARED_CARD_NOT_CONFIGURED), the source workspace archived (409 SOURCE_ARCHIVED) or you no longer an active Owner of it (409 NO_SHARED_OWNER): no workspace is created, so retrying without shareCard is safe.

How the new workspace is born

You are	Plan	Prices	Card
A regular user	Free	The standard ones	None
A reseller (marked by the Pilot Status team)	Pay As You Go, billed from the wallet	Your reseller prices: the per-number price and the phone line price agreed with you	None, unless you send `shareCard: true` — then your reserve card (shared card)

Reseller workspaces start with nothing charged: no plan fee, no numbers and no balance. The first charge is the first number that connects, or the first line you buy. The shared card is a backup: it pays a charge only when the workspace’s wallet does not cover it and the workspace has no card of its own. See Billing for resellers.

The reseller mark and the reseller prices are set by the Pilot Status team, not through the API. The team also configures which of your workspaces holds your reserve card — that is what allows you to share it. Which customer workspaces use it is your decision, per workspace: shareCard on creation, or PUT/DELETE …/shared-card afterwards. Talk to us to set them up. They apply to workspaces created from then on; workspaces you already had keep their plan.

How many workspaces you can own

Each user can own up to 10 workspaces by default, counting every workspace where you are the active Owner, your first one included. Over the limit, the answer is 409 WORKSPACE_LIMIT_REACHED, with the limit in limit:

Response (409)

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

The limit is a brake against abuse, not a plan rule. If you resell and need more, the Pilot Status team raises it for your user.

Shared card per workspace

Your reserve card is the card saved on one of your workspaces — the source workspace, chosen by the Pilot Status team for your user. A customer workspace linked to it falls back to that card when its own wallet does not cover a platform charge and it has no card of its own (its own card always comes first; the fallback is one hop: the source’s own shared card is not followed). You decide which customer workspaces are linked:

On creation: "shareCard": true on POST /v1/workspaces. Absent or false, the workspace is not linked.
Afterwards: PUT links, DELETE unlinks — below. Unlink a customer who stopped paying and your card no longer pays that customer’s renewals: a failed renewal then suspends only them.

Both endpoints require you to be the Owner of {workspaceId} — not an active member, a workspace that does not exist or is archived get 403 WORKSPACE_MEMBERSHIP_REQUIRED, and a role below Owner gets 403 PERMISSION_DENIED. They take no body (an empty body or {}); any field gets 400 UNKNOWN_FIELDS.

Link the shared card

PUT https://pilotstatus.com.br/v1/workspaces/{workspaceId}/shared-card

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

Response (200)

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

Idempotent. Already linked to the same source: 200 with "changed": false, and nothing is recorded.
The link is recorded in the workspace’s History as Backup card linked. No e-mail is sent.
409 SHARED_CARD_NOT_CONFIGURED — the Pilot Status team has not configured a reserve card for you.
400 SELF_SOURCE — {workspaceId} is the source workspace itself.
409 SOURCE_ARCHIVED — the source workspace is archived.
409 NO_SHARED_OWNER — you are no longer an active Owner of the source workspace.

Unlink the shared card

DELETE https://pilotstatus.com.br/v1/workspaces/{workspaceId}/shared-card

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

Response (200)

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

Idempotent. Not linked: 200 with "changed": false, and nothing is recorded.
The unlink is recorded in the workspace’s History as Backup card unlinked. No e-mail is sent.
From then on, the workspace’s charges use only its own wallet and card. If they do not cover a renewal, that workspace is suspended — your card is not charged.
409 NO_SHARED_OWNER — the workspace is linked to a source workspace you are not an active Owner of. Ask the Pilot Status team.

Workspace keys

These three endpoints manage the workspace keys of one workspace, with your current role in it. Not being an active member, or a workspace that does not exist or is archived, all get the same 403 WORKSPACE_MEMBERSHIP_REQUIRED.

List the keys

GET https://pilotstatus.com.br/v1/workspaces/{workspaceId}/api-keys — Owner or Admin.

Response (200)

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

The raw key never comes back here. Number keys are not listed: they are managed on /v1/api-keys.

Create a named key

POST https://pilotstatus.com.br/v1/workspaces/{workspaceId}/api-keys with { "name": "…" } — Owner or Admin.

string

required

1 to 60 characters, after trimming spaces. Use it to tell which integration holds the key.

Response (201)

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

The raw key is shown this one time only. The key is recorded as created by you, so it is revoked if you are removed from the workspace. A workspace holds up to 50 live workspace keys — revoked keys do not count; over that, 409 WORKSPACE_KEY_LIMIT_REACHED with limit.

Revoke a named key

DELETE https://pilotstatus.com.br/v1/workspaces/{workspaceId}/api-keys/{keyId} — Owner or Admin. Answers { "id": "…", "revokedAt": "…" }. The key stops working on the next request. Revoking a key that is already revoked also answers 200, with its original revokedAt, so a retry is safe.

The primary key cannot be revoked (409 PRIMARY_KEY_NOT_REVOCABLE): the in-app AI agent uses it. Rotate it instead with POST /v1/api-keys/regenerate, sending your account key and x-workspace-id (Owner role). Only the primary changes; named keys keep working.
An id that is not a workspace key of this workspace gets 404 API_KEY_NOT_FOUND. Number keys are managed on /v1/api-keys.

Errors

Status	`code`	Where	What happened
`400`	`NAME_REQUIRED`	`POST`	`name` missing or blank.
`400`	`NAME_TOO_LONG`	`POST`	`name` longer than 60 characters. `maxLength` says the limit.
`400`	`UNKNOWN_FIELDS`	`POST`, `…/shared-card`	Fields other than `name` and `shareCard` on `POST /v1/workspaces`; any field on `…/shared-card`. `unknownFields` names them.
`400`	`INVALID_SHARE_CARD`	`POST /v1/workspaces`	`shareCard` is present but not a JSON boolean (`"true"`, `1`, `null`, …).
`400`	`SELF_SOURCE`	`PUT …/shared-card`	The workspace is the source of your reserve card.
`401`	—	all	Missing, invalid or revoked key.
`403`	`ACCOUNT_KEY_REQUIRED`	all	The credential is not an account key.
`403`	`WORKSPACE_MEMBERSHIP_REQUIRED`	`…/{workspaceId}/…`	You are not an active member of that workspace, or it does not exist.
`403`	`PERMISSION_DENIED`	`…/{workspaceId}/…`	Your role there is below Admin (below Owner on `…/shared-card`).
`404`	`API_KEY_NOT_FOUND`	`DELETE`	No workspace key with that id in that workspace.
`409`	`WORKSPACE_LIMIT_REACHED`	`POST /v1/workspaces`	You already own as many workspaces as your limit. `limit` says how many.
`409`	`WORKSPACE_KEY_LIMIT_REACHED`	`POST …/api-keys`	The workspace already has 50 live (non-revoked) workspace keys.
`409`	`PRIMARY_KEY_NOT_REVOCABLE`	`DELETE`	The id is the primary key.
`409`	`SHARED_CARD_NOT_CONFIGURED`	`POST` with `shareCard: true`, `PUT …/shared-card`	No reserve card is configured for you. On `POST`, no workspace is created.
`409`	`SOURCE_ARCHIVED`	`POST` with `shareCard: true`, `PUT …/shared-card`	The source workspace of your reserve card is archived. On `POST`, no workspace is created.
`409`	`NO_SHARED_OWNER`	`POST` with `shareCard: true`, `…/shared-card`	You are not an active Owner of the source workspace. On `POST`, no workspace is created.
`500`	—	all	Unexpected failure (`Internal server error`).

On POST /v1/workspaces the checks run in this order: UNKNOWN_FIELDS, INVALID_SHARE_CARD, NAME_REQUIRED / NAME_TOO_LONG, WORKSPACE_LIMIT_REACHED, and only then, with shareCard: true, the reserve card checks (SHARED_CARD_NOT_CONFIGURED, SOURCE_ARCHIVED, NO_SHARED_OWNER).

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

Workspaces API — Create Workspaces and Their Keys

Workspaces API

List your workspaces

Create a workspace

How the new workspace is born

How many workspaces you can own

Shared card per workspace

Link the shared card

Unlink the shared card

Workspace keys

List the keys

Create a named key

Revoke a named key

Errors

​Workspaces API

​List your workspaces

​Create a workspace

​How the new workspace is born

​How many workspaces you can own

​Shared card per workspace

​Link the shared card

​Unlink the shared card

​Workspace keys

​List the keys

​Create a named key

​Revoke a named key

​Errors

Workspaces API

List your workspaces

Create a workspace

How the new workspace is born

How many workspaces you can own

Shared card per workspace

Link the shared card

Unlink the shared card

Workspace keys

List the keys

Create a named key

Revoke a named key

Errors