Session management

Use these endpoints to persist cookies and authentication state across multiple curl requests. A session is identified by a caller-provided string and is created automatically the first time that string is supplied to a request endpoint. Cookies are updated after each request. Sessions are removed after the configured idle retention period (default 720 hours), unless retention is disabled. Expired ids can start a fresh empty jar; explicitly deleted ids are tombstoned and refused for 24 hours.

Common patterns include login flows (POST login, then reuse the session for follow-up calls), token-based API authentication, and multi-step workflows that need to carry cookies between steps.

Note

The error bodies returned by every status below share a single schema whose code field is a closed enum. Each per-status tab lists the codes that status can carry. The complete set of values the field may take appears once at the end of each operation.

List all cookie sessions

GET /api/v1/curl/sessions

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

Session lifecycle:

1. Created automatically on first use with session_id.
2. Cookies are updated after each request.
3. Persists until explicitly deleted or removed by idle retention.

Common patterns:

• Login flow: POST login, save cookies, subsequent requests use the same session.
• API authentication: initial auth, the session preserves tokens.
• Multi-step workflows: each step uses the same session.

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

200

A paginated list of active sessions, sorted by last used time.

{
  "items": [
    {
      "cookies": {
        "csrftoken": "xyz789",
        "sessionid": "abc123def456"
      },
      "created_at": "2024-01-15T10:00:00Z",
      "id": "user-session-123",
      "last_used": "2024-01-15T10:30:00Z"
    },
    {
      "cookies": {
        "auth_token": "bearer_token_here"
      },
      "created_at": "2024-01-15T09:00:00Z",
      "id": "api-auth-session",
      "last_used": "2024-01-15T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "page": 1,
    "total": 2
  }
}

Error Code	Title	Description	Resolution

400

{
  "code": "INVALID_PARAMETER",
  "error": "Invalid request: timeout must be <= 7200"
}

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

SDK usage

cURL

curl "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions?page=1&limit=50"

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 });

for await (const session of client.curl.sessions.listIterator({ page: 1, limit: 50 })) {
  console.log(session.id);
}

Error code values for this operation

The code field in the shared curl_CurlErrorResponse schema is a closed enum. The complete set of values the field may take is:

Code
INVALID_PARAMETER
INVALID_URL
INVALID_CRON_EXPRESSION
PAYLOAD_TOO_LARGE
ORIGIN_NOT_ALLOWED
JOB_NOT_FOUND
JOB_RESULT_NOT_READY
SESSION_NOT_FOUND
FILE_NOT_FOUND
SCHEDULE_NOT_FOUND
SCHEDULE_EXISTS
REQUEST_TIMEOUT
JOB_NOT_FINISHED
JOB_CANCELLED
STORAGE_ERROR
INTERNAL_ERROR
SSE_PARSE_ERROR
UPSTREAM_ERROR
DNS_RESOLUTION_FAILED
RESPONSE_TOO_LARGE
QUEUE_FULL
SSE_CAPACITY_EXHAUSTED
UPSTREAM_TIMEOUT
NOT_FOUND
METHOD_NOT_ALLOWED
REQUEST_HEADERS_TOO_LARGE

Get session details

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

200

Session details with all cookies.

{
  "cookies": {
    "csrftoken": "xyz789",
    "preferences": "theme=dark",
    "sessionid": "abc123def456"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "id": "user-session-123",
  "last_used": "2024-01-15T10:30:00Z"
}

Error Code	Title	Description	Resolution

400

{
  "code": "INVALID_PARAMETER",
  "error": "Invalid request: timeout must be <= 7200"
}

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

404

{
  "code": "SESSION_NOT_FOUND",
  "error": "Session not found: cart-42 (tombstoned)"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Session does not exist	No session has this id, or it was deleted (a deleted id stays refused for 24 hours)	List sessions with client.curl.sessions.list(), or use a new session id

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

SDK usage

cURL

curl "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions/user-session-123"

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 });

const session = await client.curl.sessions.get('user-session-123');
console.log(session.data.cookies);

Error code values for this operation

The code field in the shared curl_CurlErrorResponse schema is a closed enum. The complete set of values the field may take is:

Code
INVALID_PARAMETER
INVALID_URL
INVALID_CRON_EXPRESSION
PAYLOAD_TOO_LARGE
ORIGIN_NOT_ALLOWED
JOB_NOT_FOUND
JOB_RESULT_NOT_READY
SESSION_NOT_FOUND
FILE_NOT_FOUND
SCHEDULE_NOT_FOUND
SCHEDULE_EXISTS
REQUEST_TIMEOUT
JOB_NOT_FINISHED
JOB_CANCELLED
STORAGE_ERROR
INTERNAL_ERROR
SSE_PARSE_ERROR
UPSTREAM_ERROR
DNS_RESOLUTION_FAILED
RESPONSE_TOO_LARGE
QUEUE_FULL
SSE_CAPACITY_EXHAUSTED
UPSTREAM_TIMEOUT
NOT_FOUND
METHOD_NOT_ALLOWED
REQUEST_HEADERS_TOO_LARGE

Get session cookies only

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

200

Returns the cookie jar as key-value pairs.

Error Code	Title	Description	Resolution

400

{
  "code": "INVALID_PARAMETER",
  "error": "Invalid request: timeout must be <= 7200"
}

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

404

{
  "code": "SESSION_NOT_FOUND",
  "error": "Session not found: cart-42 (tombstoned)"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Session does not exist	No session has this id, or it was deleted (a deleted id stays refused for 24 hours)	List sessions with client.curl.sessions.list(), or use a new session id

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

SDK usage

cURL

curl "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions/user-session-123/cookies"

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 });

const cookies = await client.curl.sessions.listCookies('user-session-123');
console.log(cookies.data);

Error code values for this operation

The code field in the shared curl_CurlErrorResponse schema is a closed enum. The complete set of values the field may take is:

Code
INVALID_PARAMETER
INVALID_URL
INVALID_CRON_EXPRESSION
PAYLOAD_TOO_LARGE
ORIGIN_NOT_ALLOWED
JOB_NOT_FOUND
JOB_RESULT_NOT_READY
SESSION_NOT_FOUND
FILE_NOT_FOUND
SCHEDULE_NOT_FOUND
SCHEDULE_EXISTS
REQUEST_TIMEOUT
JOB_NOT_FINISHED
JOB_CANCELLED
STORAGE_ERROR
INTERNAL_ERROR
SSE_PARSE_ERROR
UPSTREAM_ERROR
DNS_RESOLUTION_FAILED
RESPONSE_TOO_LARGE
QUEUE_FULL
SSE_CAPACITY_EXHAUSTED
UPSTREAM_TIMEOUT
NOT_FOUND
METHOD_NOT_ALLOWED
REQUEST_HEADERS_TOO_LARGE

Delete a session

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

Permanently delete a session and all its stored cookies. This action cannot be undone. The deleted id is tombstoned and stays refused for 24 hours.

Parameters

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

Response

200

Session deleted successfully.

Error Code	Title	Description	Resolution

400

{
  "code": "INVALID_PARAMETER",
  "error": "Invalid request: timeout must be <= 7200"
}

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

404

{
  "code": "SESSION_NOT_FOUND",
  "error": "Session not found: cart-42 (tombstoned)"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Session does not exist	No session has this id, or it was deleted (a deleted id stays refused for 24 hours)	List sessions with client.curl.sessions.list(), or use a new session id

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

SDK usage

cURL

curl -X DELETE "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/sessions/user-session-123"

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('user-session-123');

Error code values for this operation

The code field in the shared curl_CurlErrorResponse schema is a closed enum. The complete set of values the field may take is:

Code
INVALID_PARAMETER
INVALID_URL
INVALID_CRON_EXPRESSION
PAYLOAD_TOO_LARGE
ORIGIN_NOT_ALLOWED
JOB_NOT_FOUND
JOB_RESULT_NOT_READY
SESSION_NOT_FOUND
FILE_NOT_FOUND
SCHEDULE_NOT_FOUND
SCHEDULE_EXISTS
REQUEST_TIMEOUT
JOB_NOT_FINISHED
JOB_CANCELLED
STORAGE_ERROR
INTERNAL_ERROR
SSE_PARSE_ERROR
UPSTREAM_ERROR
DNS_RESOLUTION_FAILED
RESPONSE_TOO_LARGE
QUEUE_FULL
SSE_CAPACITY_EXHAUSTED
UPSTREAM_TIMEOUT
NOT_FOUND
METHOD_NOT_ALLOWED
REQUEST_HEADERS_TOO_LARGE