Session Management

Sessions preserve cookies across multiple HTTP requests, enabling stateful interactions with APIs that rely on authentication tokens, CSRF cookies, or multi-step workflows. Use these endpoints to inspect, snapshot, or delete session state stored by the container.

Session lifecycle:

• Created automatically on first use with a session_id
• Cookies updated after each request that uses the session
• Persists until explicitly deleted via the delete endpoint

---

Sessions

GET /api/v1/curl/sessions

Retrieve a list of all active cookie sessions, sorted by last used time. Sessions enable stateful HTTP interactions by preserving cookies across multiple requests, essential for authentication flows and stateful APIs.

Parameters

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

This endpoint accepts no request body.

cURL

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.sessions.listIterator({ page: 1, limit: 20 });

200

{
  "items": [
    {
      "id": "sess_8f3e9a2b1c4d5e6f",
      "cookies": {
        "session_token": "abc123def456ghi789",
        "auth_id": "user_42"
      },
      "scoped_cookies": [
        {
          "name": "session_token",
          "value": "abc123def456ghi789",
          "domain": "example.com",
          "path": "/",
          "secure": true,
          "host_only": false
        }
      ],
      "created_at": "2025-01-15T10:30:00Z",
      "last_used": "2025-01-15T14:22:18Z"
    },
    {
      "id": "sess_1a2b3c4d5e6f7890",
      "cookies": {
        "csrf_token": "f7g8h9i0j1k2l3m4"
      },
      "created_at": "2025-01-14T08:15:42Z",
      "last_used": "2025-01-15T09:01:33Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

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

---

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

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

Use cases:

• Inspect authentication cookies
• Debug session state issues
• Verify cookie persistence

Parameters

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

This endpoint accepts no request body.

cURL

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions/sess_8f3e9a2b1c4d5e6f" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.sessions.get('sess_8f3e9a2b1c4d5e6f');

200

{
  "id": "sess_8f3e9a2b1c4d5e6f",
  "cookies": {
    "session_token": "abc123def456ghi789",
    "auth_id": "user_42"
  },
  "scoped_cookies": [
    {
      "name": "session_token",
      "value": "abc123def456ghi789",
      "domain": "example.com",
      "path": "/",
      "secure": true,
      "host_only": false
    },
    {
      "name": "auth_id",
      "value": "user_42",
      "domain": "example.com",
      "path": "/",
      "secure": false,
      "host_only": true
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "last_used": "2025-01-15T14:22:18Z"
}

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

---

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; if the same cookie name exists under multiple domain or path scopes, the snapshot uses scope-qualified keys like name@example.com/ to avoid silently dropping entries.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Session identifier

This endpoint accepts no request body.

cURL

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions/sess_8f3e9a2b1c4d5e6f/cookies" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.sessions.getCookies('sess_8f3e9a2b1c4d5e6f');

200

{
  "session_token": "abc123def456ghi789",
  "auth_id": "user_42",
  "preference@api.example.com/": "dark-mode"
}

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

---

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

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

Caution

Deleting a session immediately invalidates all cookies it contains. Any subsequent requests that depend on the session ID will fail authentication or session lookup.

Parameters

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

This endpoint accepts no request body.

cURL

curl -X DELETE "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions/sess_8f3e9a2b1c4d5e6f" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.sessions.delete('sess_8f3e9a2b1c4d5e6f');

200

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

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