Session API for Sticky Proxy Management in ProxyMapService

In a previous article, Making Any Scraper Work with Sticky Proxies, we discussed how ProxyMapService maps local ports to independent sticky proxy sessions.

Each local port automatically receives its own session ID and keeps it for the configured StickyProxyLifetime. This allows applications that only support simple IP:PORT proxies to work with modern session-based proxy providers.

Until now, session management in ProxyMapService was completely automatic. While this works well for many use cases, some applications need direct control over when sessions are created, rotated, or discarded.

The latest version of ProxyMapService introduces a Session API that allows applications and scripts to inspect, reset, and create sessions on demand.

How sessions work

Assume the following configuration:

{
  "Listen": {
    "PortRange": {
      "Start": 10201,
      "End": 10300
    },
    "StickyProxyLifetime": 10
  }
}

When traffic is sent through port 10201, ProxyMapService generates a session ID:

10201 → session LZpmRqdu

All requests made through this port will use the same sticky session until it expires.

The new Session API exposes this information and allows manual control over the session lifecycle.

Enabling Session API

For security and compatibility reasons, Session API is disabled by default.

To enable it, add the following section to your appsettings.json:

{
  "SessionAPI": {
    "Enabled": true,
    "Domain": "portmapper"
  }
}

Configuration Options

Option	Description
Enabled	Enables Session API endpoints.
Domain	Virtual domain used to access Session API endpoints through a mapped proxy port.

With the configuration above, Session API can be accessed using requests such as:

curl -x http://127.0.0.1:10201 http://portmapper/session/

Using an Empty Domain

The Domain setting is optional and may be set to an empty string:

{
  "SessionAPI": {
    "Enabled": true,
    "Domain": ""
  }
}

When Domain is empty, Session API endpoints become available directly on the mapped proxy port.

For example:

curl http://127.0.0.1:10201/session/

This can be convenient when working with local tools or scripts that do not support custom hostnames.

Get Current Session

Returns information about the session currently assigned to a port.

Example:

curl -x http://127.0.0.1:10201 http://portmapper/session/

Response:

{
  "session_id": "LZpmRqdu",
  "expires_at": "Wed, 10 Jun 2026 16:09:43 GMT",
  "expired": false
}

If the session is still active, repeated calls return the same information.

When the sticky session expires, ProxyMapService automatically generates a new session ID and the endpoint will return the new session details.

This can be useful for monitoring session state or checking how much time remains before rotation.

Reset Current Session

Sometimes you want to force a session change without waiting for the expiration timer.

The /session/reset endpoint removes the current session associated with the port.

Example:

curl -x http://127.0.0.1:10201 http://portmapper/session/reset

Response:

{
  "success": true
}

After the reset, the next request through port 10201 will automatically create a new session.

Typical use cases:

• detected or blocked IP address
• captcha escalation
• failed scraping workflow
• manual IP rotation

Create a New Session Immediately

The /session/new endpoint creates a new session immediately and assigns it to the port.

Example:

curl -x http://127.0.0.1:10201 http://portmapper/session/new

Response:

{
  "session_id": "uawxmttg",
  "expires_at": "Wed, 10 Jun 2026 16:19:48 GMT",
  "expired": false
}

Unlike /session/reset, which simply removes the current session, /session/new generates and activates a replacement session instantly.

This is useful when an application wants to rotate identities proactively while continuing to use the same local proxy port.

Why Not Just Change Ports?

A common question is why you would need a Session API if every port already has its own sticky session.

In practice, many scraping and automation systems assign a specific role to each local proxy port. For example:

127.0.0.1:10201 → Worker A
127.0.0.1:10202 → Worker B
127.0.0.1:10203 → Worker C

Workers may maintain their own queues, browser profiles, cookies, account assignments, or internal state tied to a particular proxy endpoint.

Changing ports is not always practical because it may require updating application configuration, restarting workers, or reassigning tasks.

With Session API, the application can keep using the same local proxy port while rotating the underlying sticky session whenever necessary.

Practical Examples

Session API can be useful when:

• a target website starts returning captchas
• an IP address becomes blocked or rate-limited
• a scraping task needs a fresh identity immediately
• monitoring systems need visibility into session expiration
• applications want explicit control over session rotation timing

All of this can be done without restarting ProxyMapService and without changing the local proxy endpoint used by the application.

Summary

ProxyMapService was originally designed to make sticky proxies available to software that only understands simple IP:PORT proxy lists.

The new Session API adds direct control over the sticky sessions behind each mapped port.

Available endpoints:

• GET /session/ — get information about the current session
• GET /session/reset — remove the current session
• GET /session/new — create and activate a new session immediately

This makes it easier to build scraping, automation, and data collection systems that need predictable control over proxy identities while continuing to use ordinary local proxy ports.