Get Session Context

Produce a context object from the Session. The caller provides an optional token limit which the entire context must fit into. If not provided, the context will be exhaustive (within configured max tokens). To do this, we allocate 40% of the token limit to the summary, and 60% to recent messages — as many as can fit. Note that the summary will usually take up less space than this. If the caller does not want a summary, we allocate all the tokens to recent messages.

GET /v3/workspaces/{workspace_id}/sessions/{session_id}/context

Get Session Context

cURL

curl --request GET \
  --url https://api.honcho.dev/v3/workspaces/{workspace_id}/sessions/{session_id}/context \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "<string>",
  "messages": [
    {
      "id": "<string>",
      "content": "<string>",
      "peer_id": "<string>",
      "session_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "workspace_id": "<string>",
      "token_count": 123,
      "metadata": {}
    }
  ],
  "summary": {
    "content": "<string>",
    "message_id": "<string>",
    "summary_type": "<string>",
    "created_at": "<string>",
    "token_count": 123
  },
  "peer_representation": "<string>",
  "peer_card": [
    "<string>"
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspace_id · string · required

session_id · string · required

Query Parameters

tokens · integer | null

Number of tokens to use for the context. Includes summary if set to true. Includes representation and peer card if they are included in the response. If not provided, the context will be exhaustive (within 100000 tokens)

Required range: x <= 100000

search_query · string | null

A query string used to fetch semantically relevant conclusions

summary · boolean · default: true

Whether or not to include a summary if one is available for the session

peer_target · string | null

The target of the perspective. If given without peer_perspective, will get the Honcho-level representation and peer card for this peer. If given with peer_perspective, will get the representation and card for this peer from the perspective of that peer.

peer_perspective · string | null

A peer to get context for. If given, response will attempt to include representation and card from the perspective of that peer. Must be provided with peer_target.

scope · string | null

An (unprefixed) scope name to use as the perspective source: the representation and peer card of peer_target are read from the scope's observations instead of the global (or peer_perspective) view. Must be provided with peer_target; mutually exclusive with peer_perspective. Requires a workspace- or admin-level key.

sessions · string[] | null

Optional allowlist of session IDs confining the representation of peer_target to those sessions. This session must be one of them. Recall is restricted to conclusions stated directly in the allowed sessions — conclusions synthesized across sessions are excluded, since their provenance cannot be proven to sit inside the allowlist — and the peer card is omitted for the same reason. Mutually exclusive with scope and limit_to_session. A peer-scoped key must be an active member of every session named. The 1,000-session cap shared with the recall endpoints applies but is not reachable here: these are repeated query parameters, so a long list exceeds the request-line limit of the server or any proxy in front of it (a 414/431, not a 422) at a few hundred entries. Use a named scope for large or reusable session sets.

limit_to_session · boolean · default: false

Whether to limit the representation to the session (as opposed to everything known about the target peer). Narrows recall the same way sessions does, so the same restrictions apply: explicit-only conclusions, and the peer card is omitted because it carries no per-session provenance.

search_top_k · integer | null

Only used if search_query is provided. The number of semantic-search-retrieved conclusions to include in the representation

Required range: 1 <= x <= 100

search_max_distance · number | null

Only used if search_query is provided. The maximum distance to search for semantically relevant conclusions

Required range: 0 <= x <= 1

include_most_frequent · boolean · default: false

Only used if search_query is provided. Whether to include the most frequent conclusions in the representation

max_conclusions · integer | null

Only used if search_query is provided. The maximum number of conclusions to include in the representation

Required range: 1 <= x <= 100

Response

200

application/json

Successful Response

id · string · required

messages · Message · object[] · required

Show child attributes

summary · Summary · object | null

The summary if available

Show child attributes

peer_representation · string | null

A curated subset of a peer representation, if context is requested from a specific perspective

peer_card · string[] | null

The peer card, if context is requested from a specific perspective