Switch API reference

Switch

The carrier switch: account-level settings, mode and overview. Every Switch operation requires a Switch plan.

3 operationsBase URL https://packetexchange.io/api/v1Postman collection

Count customers, trunks, suppliers and other Switch records

GET/api/v1/switch/entity-counts

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Headline counts for the Switch overview and navigation.

Response 200

Field	Type	Description
`data`required	object	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your Switch console mode

GET/api/v1/switch/mode

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

ai (AI Control) or advanced (the full console); null when never chosen, which the dashboard treats as AI Control. aiAvailable is false for team members without team.manage.

Response 200

Field	Type	Description
`data`required	object	-
`mode`requireddata.mode	string \| null	-One of `ai`, `advanced`
`aiAvailable`requireddata.aiAvailable	boolean	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Set your Switch console mode

PUT/api/v1/switch/mode

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

A display preference only; nothing on the switch changes.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`mode`required	string	-One of `ai`, `advanced`

Response 200

Field	Type	Description
`data`required	object	-
`mode`requireddata.mode	string	-One of `ai`, `advanced`

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/switch/mode" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "ai"
}'

Run it here with a test key.