> ## Documentation Index > Fetch the complete documentation index at: https://developers.soax.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a stateful session > Change a session's name, status or rules. Your client keeps the same connection string; the next request picks up the change. Renaming is the exception: the username is `stateful-`, so a rename changes it. Send only what you want to change. In `ruleset`, an omitted field keeps its stored value and an explicit `null` clears a geo field or `network_type`. `lookalike`, `rotation_trigger` and `error_handling` cannot be `null`. Changing a geo field to a different value clears the fields beneath it that you did not send: changing `country` clears `region`, `city`, `isp`, `asn` and `zip`; changing `region` clears `city`, `isp`, `asn` and `zip`; changing `city` clears `isp`, `asn` and `zip`. `isp`, `asn` and `zip` never clear one another. Set `status` to `disabled` to stop a session carrying traffic without losing its name, port or rules, and back to `enabled` to resume. Re-enabling binds a new node; if none is available the call returns `502` and the session stays disabled. Requires the `proxy:packages:write` scope. ## OpenAPI ````yaml api/openapi.json PATCH /v1/proxy/packages/{package_id}/stateful-sessions/{session_id} openapi: 3.1.0 info: title: SOAX API version: v1 description: >- Programmatic access to your SOAX account: manage proxy packages, generate connection strings, browse available locations, pull usage analytics, and manage API keys. All endpoints are served over HTTPS and return JSON. servers: - url: https://api.platform.soax.com security: - bearerAuth: [] tags: - name: API Keys description: >- Self-service management of the API keys used to authenticate with this API. - name: Packages description: >- Read proxy packages, build proxy connection strings, and rotate package passwords. - name: Stateful Sessions description: Create and manage long-lived, server-configured proxy sessions. - name: Locations description: >- Location reference data: tiers, countries, regions, cities, ISPs, ASNs, and ZIP codes. - name: Account description: Read-only account, credit, and subscription information. - name: Analytics description: Usage analytics for your proxy packages. paths: /v1/proxy/packages/{package_id}/stateful-sessions/{session_id}: patch: tags: - Stateful Sessions summary: Update a stateful session description: >- Change a session's name, status or rules. Your client keeps the same connection string; the next request picks up the change. Renaming is the exception: the username is `stateful-`, so a rename changes it. Send only what you want to change. In `ruleset`, an omitted field keeps its stored value and an explicit `null` clears a geo field or `network_type`. `lookalike`, `rotation_trigger` and `error_handling` cannot be `null`. Changing a geo field to a different value clears the fields beneath it that you did not send: changing `country` clears `region`, `city`, `isp`, `asn` and `zip`; changing `region` clears `city`, `isp`, `asn` and `zip`; changing `city` clears `isp`, `asn` and `zip`. `isp`, `asn` and `zip` never clear one another. Set `status` to `disabled` to stop a session carrying traffic without losing its name, port or rules, and back to `enabled` to resume. Re-enabling binds a new node; if none is available the call returns `502` and the session stays disabled. Requires the `proxy:packages:write` scope. operationId: >- update_stateful_session_v1_proxy_packages__package_id__stateful_sessions__session_id__patch parameters: - name: package_id in: path required: true schema: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ description: The ID of the proxy package (UUID format) title: Package Id description: The ID of the proxy package (UUID format) - name: session_id in: path required: true schema: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ description: The ID of the stateful session (UUID format) title: Session Id description: The ID of the stateful session (UUID format) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StatefulSessionUpdateRequest' examples: move: summary: Move the session to Germany value: ruleset: country: de pin: summary: Pin the current node value: ruleset: rotation_trigger: bind error_handling: fail disable: summary: Disable the session value: status: disabled responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/StatefulSessionResponse' example: id: 7c1e9a52-3b4d-4f6a-9e8b-2d5c0a1f6b3e proxy_id: b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e name: checkout1 status: enabled ruleset: network_type: wifi country: us region: california city: null isp: null asn: null zip: null lookalike: false rotation_trigger: timed:300 error_handling: replace exit_ip: 203.0.113.42 network_type: wifi country: us region: california city: los_angeles isp: charter_communications asn: '20001' zip: null bound_since: '2026-10-27T10:15:04Z' port: 1337 created_at: '2026-10-27T10:15:03Z' updated_at: '2026-10-27T10:15:04Z' connection_string: uri: stateful-checkout1:aB3dE5fG7h@proxy.soax.com:1337 username: stateful-checkout1 password: aB3dE5fG7h host: proxy.soax.com port: 1337 '400': description: Invalid name or ruleset. content: application/json: example: detail: rotation_trigger=bind conflicts with error_handling=replace. '401': $ref: '#/components/responses/Unauthorized' '403': description: The API key does not carry the scope this endpoint requires. content: application/json: schema: type: object properties: detail: type: string example: detail: 'Missing required scope: proxy:packages:write' '404': description: Session not found, or outside the API key's package restriction. content: application/json: example: detail: Session not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': $ref: '#/components/responses/RateLimited' '502': description: >- Re-enabling failed because no node could be assigned. The session stays disabled. content: application/json: example: detail: The session could not be assigned a node; it remains disabled. components: schemas: StatefulSessionUpdateRequest: properties: name: anyOf: - type: string - type: 'null' title: Name description: >- New name, `^[a-z0-9]{1,16}$`. Changes the connection string username. ruleset: anyOf: - $ref: '#/components/schemas/StatefulSessionRequestRulesetSchema' - type: 'null' description: Rules to change. Omitted fields keep their stored value. status: anyOf: - $ref: '#/components/schemas/StatefulSessionStatus' - type: 'null' description: '`enabled` or `disabled`.' type: object title: StatefulSessionUpdateRequest StatefulSessionResponse: properties: id: type: string title: Id proxy_id: type: string title: Proxy Id name: type: string title: Name status: $ref: '#/components/schemas/StatefulSessionStatus' description: '`enabled` or `disabled`.' ruleset: $ref: '#/components/schemas/StatefulSessionRulesetSchema' description: 'The rules you set: what the session is allowed to use.' exit_ip: type: string title: Exit Ip description: IP address of the exit node the session is bound to now. network_type: type: string title: Network Type description: >- Network of the bound node. The top-level geo and network fields describe where the session is bound now; `ruleset` holds what you asked for. country: type: string title: Country region: anyOf: - type: string - type: 'null' title: Region city: anyOf: - type: string - type: 'null' title: City isp: anyOf: - type: string - type: 'null' title: Isp asn: anyOf: - type: string - type: 'null' title: Asn zip: anyOf: - type: string - type: 'null' title: Zip bound_since: anyOf: - type: string format: date-time - type: 'null' title: Bound Since description: When the session was bound to its current node. port: anyOf: - type: integer - type: 'null' title: Port description: >- Gateway port to connect to. IP allowlist packages get a dedicated port per session; credential packages share the gateway port. created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At connection_string: anyOf: - $ref: '#/components/schemas/ConnectionStringSchema' - type: 'null' description: >- How to connect. For credential packages the username is `stateful-` and the password is the package key. For IP allowlist packages `username` and `password` are empty and `uri` is `host:port`. type: object required: - id - proxy_id - name - status - ruleset - exit_ip - network_type - country - created_at - updated_at title: StatefulSessionResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError StatefulSessionRequestRulesetSchema: properties: network_type: anyOf: - type: string enum: - wifi - mobile - any - type: 'null' title: Network Type description: >- `wifi` (residential), `mobile`, or `any`. Must be enabled on the package. country: anyOf: - type: string - type: 'null' title: Country description: >- Two-letter country code, or `any`. Must be available on the package. Required when any of `region`, `city`, `isp`, `asn` or `zip` is set. region: anyOf: - type: string - type: 'null' title: Region description: >- Region code from the package location endpoints. Must belong to `country`. city: anyOf: - type: string - type: 'null' title: City description: >- City code from the package location endpoints. Must belong to `region`, or to `country` when no region is set. isp: anyOf: - type: string - type: 'null' title: Isp description: >- ISP code from the package location endpoints, valid for the chosen country, region and city. asn: anyOf: - type: string - type: 'null' title: Asn description: >- ASN from the package location endpoints. Requires ASN targeting on your plan. zip: anyOf: - type: string - type: 'null' title: Zip description: >- ZIP code from the package location endpoints. Requires ZIP targeting on your plan. lookalike: anyOf: - type: boolean - type: 'null' title: Lookalike description: >- `true` or `false`: whether a replacement node should resemble the previous one (same ISP and location where possible). Defaults to `false` on create. Cannot be `true` with `rotation_trigger: "bind"`. On update, omit it to keep the stored value; `null` is rejected (422). rotation_trigger: anyOf: - type: string - type: 'null' title: Rotation Trigger description: >- When the exit node changes: `timed:` (minimum 10), `request-count:`, `on-error` (only when the node fails) or `bind` (pin the node). Defaults to `timed:300` on create. `bind` cannot be combined with `error_handling: "replace"` or `lookalike: true`. On update, omit it to keep the stored value; `null` is rejected (422). error_handling: anyOf: - type: string - type: 'null' title: Error Handling description: >- What happens when the bound node fails: `replace` (switch to a new node), `retry_` (retry on the same node first) or `fail` (return the error). Defaults to `replace` on create, or `retry_3` when `rotation_trigger` is `bind`. On update, omit it to keep the stored value; `null` is rejected (422). type: object title: StatefulSessionRequestRulesetSchema StatefulSessionStatus: type: string enum: - enabled - disabled title: StatefulSessionStatus StatefulSessionRulesetSchema: properties: network_type: anyOf: - type: string enum: - wifi - mobile - any - type: 'null' title: Network Type description: >- `wifi` (residential), `mobile`, or `any`. Must be enabled on the package. country: anyOf: - type: string - type: 'null' title: Country description: >- Two-letter country code, or `any`. Must be available on the package. Required when any of `region`, `city`, `isp`, `asn` or `zip` is set. region: anyOf: - type: string - type: 'null' title: Region description: >- Region code from the package location endpoints. Must belong to `country`. city: anyOf: - type: string - type: 'null' title: City description: >- City code from the package location endpoints. Must belong to `region`, or to `country` when no region is set. isp: anyOf: - type: string - type: 'null' title: Isp description: >- ISP code from the package location endpoints, valid for the chosen country, region and city. asn: anyOf: - type: string - type: 'null' title: Asn description: >- ASN from the package location endpoints. Requires ASN targeting on your plan. zip: anyOf: - type: string - type: 'null' title: Zip description: >- ZIP code from the package location endpoints. Requires ZIP targeting on your plan. lookalike: anyOf: - type: boolean - type: 'null' title: Lookalike description: Whether a replacement node should resemble the previous one. rotation_trigger: anyOf: - type: string - type: 'null' title: Rotation Trigger description: >- `bind`, `on-error`, `timed:` (minimum 10) or `request-count:`. error_handling: anyOf: - type: string - type: 'null' title: Error Handling description: '`replace`, `fail` or `retry_`.' type: object title: StatefulSessionRulesetSchema ConnectionStringSchema: properties: uri: type: string title: Uri username: type: string title: Username password: anyOf: - type: string - type: 'null' title: Password host: type: string title: Host port: type: integer title: Port type: object required: - uri - username - host - port title: ConnectionStringSchema ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError responses: Unauthorized: description: Missing, invalid, or revoked API key. content: application/json: schema: type: object properties: detail: type: string example: detail: Invalid API key RateLimited: description: >- Rate limit exceeded (5 requests/second per API key, 500 requests/minute per IP). The response includes `Retry-After` (seconds), `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (Unix time) headers — wait `Retry-After` seconds and retry. content: application/json: schema: type: object properties: error: type: string example: error: 'Rate limit exceeded: 5 per 1 second' securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key secret (starts with `s_live_`). Create keys in the dashboard under **Settings → API keys**, or via `POST /v1/api-keys/`. Send it as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.