Upgrade Service
Submit a service plan upgrade and track background processing.
admin:full.
Choose a plan
- Use List Plans to find active plans for your broker.
- Choose a plan with an
upgrade_rankhigher than the current plan’s rank and the samebilling_type. - Send its
slug,id, or display name innew_plan. Slugs and display names are matched case-insensitively.
Track the result
200 with request_status: "accepted" means the work was queued, not that the plan has changed. HTTP 202 with nycservers_review means NYCServers must review the request. Do not resubmit it.request_id and check List Requests. Check the related service for its current plan and specifications, and follow any setup or reboot instructions sent to the client.
Use Errors and Retries to handle uncertain outcomes and X-Idempotency-Key safely.
Endpoint errors
For authentication, permissions, rate limits, and safe retries, see Errors and Retries.400 invalid_state; it requires cancellation and recreation rather than a plan change.Authorizations
Send the API key in the Authorization bearer header. Production keys begin with sk_live_.
Headers
Unique key for one intended operation. Reuse with unchanged input for retries. Supported by service creation, plan changes, cancellation, and request approval (not denial). Creation replays by key without checking changed input; action payload conflicts can return 409. See /api/errors-and-retries for endpoint-specific behavior.
Path Parameters
Public service number parsed as a base-10 integer.
Body
Active broker catalog plan id, slug, or display name. Slugs and display names are matched case-insensitively. Use GET /v1/plans for available choices. Live direction follows upgrade_rank and billing_type must match. Sandbox plan changes use the four standard plans instead.

