Overview

Sessions persist cookies and authentication state across multiple HTTP requests, enabling stateful interactions with APIs that require login flows or session-based authentication. Each session stores a cookie jar that is automatically updated after each request, allowing subsequent requests to reuse authentication tokens and session identifiers.

Use the session management endpoints to inspect existing sessions, retrieve stored cookies for debugging, or clean up sessions that are no longer needed.

Session lifecycle:

1. Created automatically on first request that includes a session_id
2. Cookies are updated after each request that uses the session
3. Persists until explicitly deleted via the delete endpoint

List sessions

GET /api/v1/curl/sessions

Retrieve a paginated list of all active cookie sessions, sorted by last used time.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	1-based page number
limit	query	integer	No	Items per page (when omitted, the handler returns all items)

Response

200

{
  "items": [
    {
      "id": "sess_a1b2c3d4e5f6",
      "cookies": {
        "session_token": "abc123def456",
        "auth": "Bearer xyz789"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "last_used": "2026-01-15T14:22:18Z",
      "scoped_cookies": [
        {
          "name": "session_token",
          "value": "abc123def456",
          "domain": "api.example.com",
          "path": "/",
          "secure": true,
          "host_only": true
        }
      ]
    },
    {
      "id": "sess_f6e5d4c3b2a1",
      "cookies": {
        "csrf_token": "tok_9988776655"
      },
      "created_at": "2026-01-14T09:15:42Z",
      "last_used": "2026-01-15T08:05:11Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read sessions"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Unable to read sessions from persistent storage	Check storage permissions and disk availability

SDK Usage

for session in client.curl.sessions.listIterator():
    print(session.id, session.last_used)

# With explicit pagination
for session in client.curl.sessions.listIterator(page=1, limit=20):
    print(session.id)

Get session details

GET /api/v1/curl/sessions/{id}

Retrieve complete details for a specific cookie session, including all stored cookies, creation time, and last usage timestamp.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Session identifier (caller-provided string)

Response

200

{
  "id": "sess_a1b2c3d4e5f6",
  "cookies": {
    "session_token": "abc123def456",
    "auth": "Bearer xyz789"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "last_used": "2026-01-15T14:22:18Z",
  "scoped_cookies": [
    {
      "name": "session_token",
      "value": "abc123def456",
      "domain": "api.example.com",
      "path": "/",
      "secure": true,
      "host_only": true
    },
    {
      "name": "auth",
      "value": "Bearer xyz789",
      "domain": "api.example.com",
      "path": "/v1",
      "secure": true,
      "host_only": false
    }
  ]
}

404

{
  "error": "SESSION_NOT_FOUND",
  "message": "Session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Session does not exist	No session found with the provided ID	Verify session ID using listSessions or create new session

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read session"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Failed to read session data from storage	Check storage integrity and retry

SDK Usage

session = client.curl.sessions.get("sess_a1b2c3d4e5f6")
print(session.cookies)
print(session.last_used)

Get session cookies

GET /api/v1/curl/sessions/{id}/cookies

Retrieve only the cookie snapshot from a session, without metadata. Unique cookie names are returned as plain keys. When the same cookie name exists under multiple domain/path scopes, the snapshot uses scope-qualified keys such as name@example.com/ to avoid silently dropping entries.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Session identifier

Response

200

{
  "session_token": "abc123def456",
  "auth": "Bearer xyz789",
  "csrf_token@example.com/": "tok_9988776655"
}

404

{
  "error": "SESSION_NOT_FOUND",
  "message": "Session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Session does not exist	No session found with the provided ID	Verify session ID using listSessions

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read cookies"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Failed to read session cookies from storage	Check storage permissions and retry

SDK Usage

cookies = client.curl.sessions.getCookies("sess_a1b2c3d4e5f6")
print(cookies)

Delete a session

DELETE /api/v1/curl/sessions/{id}

Permanently delete a session and all its stored cookies. This action cannot be undone.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Session identifier to delete

Response

200

{
  "success": true,
  "id": "sess_a1b2c3d4e5f6"
}

404

{
  "error": "SESSION_NOT_FOUND",
  "message": "Session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Session does not exist	Cannot delete session that doesn’t exist	Verify session ID using listSessions endpoint

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to delete session"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage delete failed	Session exists but could not be deleted from storage	Check storage permissions and retry operation

SDK Usage

client.curl.sessions.delete("sess_a1b2c3d4e5f6")