Session Management

Sessions persist cookies and authentication state across multiple HTTP requests, enabling stateful interactions with APIs that require login flows, session tokens, or multi-step workflows. Each session maintains a cookie jar that is automatically updated after every request that uses it.

Session lifecycle:

Created automatically on first use with a session_id
Cookies updated after each request
Persists until explicitly deleted

Use these endpoints to inspect, retrieve, or delete sessions created by the Hoody cURL service.

`GET /api/v1/curl/sessions`

Retrieve a 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 (current handler returns all items when omitted)

Response

{
  "items": [
    {
      "id": "sess_8f3a2b1c",
      "cookies": {
        "session_token": "abc123def456",
        "csrf_token": "xyz789"
      },
      "created_at": "2026-01-15T10:30:00.000Z",
      "last_used": "2026-01-15T14:22:05.000Z"
    },
    {
      "id": "sess_9d4e5f6a",
      "cookies": {
        "auth_token": "Bearer eyJhbGciOi..."
      },
      "created_at": "2026-01-14T08:15:00.000Z",
      "last_used": "2026-01-15T09:00:00.000Z",
      "scoped_cookies": [
        {
          "name": "auth_token",
          "value": "Bearer eyJhbGciOi...",
          "domain": "api.example.com",
          "path": "/",
          "secure": true,
          "host_only": true
        }
      ]
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

{
  "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

curl -X GET "https://proj-abc123-cont456-curl-1.us-east-1.containers.hoody.icu/api/v1/curl/sessions?page=1&limit=20"

// List all sessions (paginated)
const sessions = await client.curl.sessions.listIterator();

// Or with pagination options
const sessions = await client.curl.sessions.listIterator({ page: 1, limit: 20 });

`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)

Response

{
  "id": "sess_8f3a2b1c",
  "cookies": {
    "session_token": "abc123def456",
    "csrf_token": "xyz789"
  },
  "created_at": "2026-01-15T10:30:00.000Z",
  "last_used": "2026-01-15T14:22:05.000Z",
  "scoped_cookies": [
    {
      "name": "session_token",
      "value": "abc123def456",
      "domain": "app.example.com",
      "path": "/",
      "secure": true,
      "host_only": true
    },
    {
      "name": "csrf_token",
      "value": "xyz789",
      "domain": "app.example.com",
      "path": "/",
      "secure": true,
      "host_only": true
    }
  ]
}

{
  "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

{
  "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

cURL
TypeScript SDK

curl -X GET "https://proj-abc123-cont456-curl-1.us-east-1.containers.hoody.icu/api/v1/curl/sessions/sess_8f3a2b1c"

const session = await client.curl.sessions.get("sess_8f3a2b1c");

`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

Response

{
  "session_token": "abc123def456",
  "csrf_token": "xyz789",
  "auth_token@example.com/": "Bearer eyJhbGciOi..."
}

{
  "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

{
  "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

cURL
TypeScript SDK

curl -X GET "https://proj-abc123-cont456-curl-1.us-east-1.containers.hoody.icu/api/v1/curl/sessions/sess_8f3a2b1c/cookies"

const cookies = await client.curl.sessions.getCookies("sess_8f3a2b1c");

`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

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

{
  "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

{
  "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

cURL
TypeScript SDK

curl -X DELETE "https://proj-abc123-cont456-curl-1.us-east-1.containers.hoody.icu/api/v1/curl/sessions/sess_8f3a2b1c"

await client.curl.sessions.delete("sess_8f3a2b1c");