Skip to content

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
BrowseSwitch

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

  • datarequired

    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

  • datarequired

    object

  • moderequired

    string | null · data.mode

    One of ai, advanced

  • aiAvailablerequired

    boolean · data.aiAvailable

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)

  • moderequired

    string

    One of ai, advanced

Response 200

  • datarequired

    object

  • moderequired

    string · data.mode

    One of ai, advanced

Response 202

  • datarequired

    object

  • approvalRequired

    boolean · data.approvalRequired

    One of true

  • approvalRequestId

    string (uuid) | null · data.approvalRequestId

  • permission

    string · data.permission

  • expiresAt

    string (date-time) · data.expiresAt

  • message

    string · data.message

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.