# Sessions

> The Sessions operations of the Hub REST API (10 operations).

URL: https://docs.synap.live/docs/reference/hub-api/sessions · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## POST /sessions/getOrCreate

Get or create a session for a channel

Returns the active session for the channel or creates one. Sessions are scoped to a chat/channel; supports a `bootstrapStateId` to start from a compacted state.

Request body (`application/json`): GetOrCreateSessionRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | yes |  |
| `bootstrapStateId` | string |  | Compacted-state ID to bootstrap the session from. |

Responses:

- `200`: Session
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /sessions/active

Get the active session for a channel

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `channelId` | query | string | yes |  |

Responses:

- `200`: Active session, or null if none is open
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /sessions/{sessionId}

Get a session by id

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

Responses:

- `200`: Session
- `403`: Forbidden
- `404`: Session not found
- `500`: Internal error

## PATCH /sessions/{sessionId}

Update a session

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

Request body (`application/json`): UpdateSessionRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `metadata` | object |  |  |
| `bootstrapStateId` | string |  |  |
| `producedStateId` | string |  |  |

Responses:

- `200`: Updated session
- `400`: Bad request
- `403`: Forbidden
- `404`: Session not found
- `500`: Internal error

## GET /sessions

List sessions for a channel

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `channelId` | query | string | yes |  |
| `limit` | query | string |  |  |

Responses:

- `200`: Sessions
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /sessions/{sessionId}/close

Close a session

Closes a session and optionally records the produced compacted-state id.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionId` | path | string | yes |  |

Request body (`application/json`): CloseSessionRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `producedStateId` | string |  | Compacted-state ID written at session close. |

Responses:

- `200`: Closed session
- `400`: Bad request
- `403`: Forbidden
- `404`: Session not found
- `500`: Internal error

## GET /compacted-states

List compacted states for a channel

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `channelId` | query | string | yes |  |
| `limit` | query | string |  |  |

Responses:

- `200`: Compacted states (newest first)
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /compacted-states

Create a compacted state

Persists a summarized state snapshot for a channel. Used to bootstrap subsequent sessions cheaply.

Request body (`application/json`): CreateCompactedStateRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | yes |  |
| `sessionId` | string |  |  |
| `summary` | string |  |  |
| `facts` | array<object> |  |  |
| `metadata` | object |  |  |

Responses:

- `200`: Created compacted state
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /compacted-states/latest

Get the latest compacted state for a channel

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `channelId` | query | string | yes |  |

Responses:

- `200`: Latest compacted state, or null
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /compacted-states/{stateId}

Get a compacted state by id

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `stateId` | path | string | yes |  |

Responses:

- `200`: Compacted state
- `403`: Forbidden
- `404`: State not found
- `500`: Internal error