# Session Management

**Page:** api/curl/sessions

[Download Raw Markdown](./api/curl/sessions.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Session Management

Cookie sessions preserve authentication state and cookies across multiple HTTP requests. Use these endpoints to inspect, list, and manage sessions created during curl-based interactions. Sessions are created automatically on first use with a `session_id` and persist until explicitly deleted.


  Common patterns include login flows (POST login → save cookies → subsequent requests reuse the session), API authentication (initial auth → session preserves tokens), and multi-step workflows where each step relies on the same cookie jar.


---

### `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 (optional) |
| `limit` | query | integer | No | Items per page (optional; current handler returns all items when omitted) |

This endpoint accepts no request body.



```bash
curl -G https://api.hoody.com/api/v1/curl/sessions \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"
```


```python
client.curl.sessions.listIterator(
    page=1,
    limit=20,
)
```


```json
{
  "items": [
    {
      "id": "sess_abc123def456",
      "cookies": {
        "session_id": "eyJpZCI6MTIzfQ==",
        "csrf_token": "tk_9f8e7d6c5b4a"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "last_used": "2024-01-15T14:22:15Z",
      "scoped_cookies": [
        {
          "domain": "api.example.com",
          "host_only": true,
          "name": "session_id",
          "path": "/",
          "secure": true,
          "value": "eyJpZCI6MTIzfQ=="
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```


```json
{
  "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.

### Parameters

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

This endpoint accepts no request body.



```bash
curl https://api.hoody.com/api/v1/curl/sessions/sess_abc123def456 \
  -H "Authorization: Bearer <token>"
```


```python
client.curl.sessions.get(
    id="sess_abc123def456",
)
```


```json
{
  "id": "sess_abc123def456",
  "cookies": {
    "session_id": "eyJpZCI6MTIzfQ==",
    "csrf_token": "tk_9f8e7d6c5b4a"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "last_used": "2024-01-15T14:22:15Z",
  "scoped_cookies": [
    {
      "domain": "api.example.com",
      "host_only": true,
      "name": "session_id",
      "path": "/",
      "secure": true,
      "value": "eyJpZCI6MTIzfQ=="
    },
    {
      "domain": "api.example.com",
      "host_only": true,
      "name": "csrf_token",
      "path": "/",
      "secure": true,
      "value": "tk_9f8e7d6c5b4a"
    }
  ]
}
```


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


```json
{
  "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.



```bash
curl https://api.hoody.com/api/v1/curl/sessions/sess_abc123def456/cookies \
  -H "Authorization: Bearer <token>"
```


```python
client.curl.sessions.getCookies(
    id="sess_abc123def456",
)
```


```json
{
  "session_id": "eyJpZCI6MTIzfQ==",
  "csrf_token": "tk_9f8e7d6c5b4a"
}
```


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


```json
{
  "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.

### Parameters

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

This endpoint accepts no request body.



```bash
curl -X DELETE https://api.hoody.com/api/v1/curl/sessions/sess_abc123def456 \
  -H "Authorization: Bearer <token>"
```


```python
client.curl.sessions.delete(
    id="sess_abc123def456",
)
```


```json
{
  "id": "sess_abc123def456",
  "deleted": true
}
```


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


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




  Deleting a session removes all stored cookies. Any in-flight workflows that depend on the session will lose authentication state.