Get Representation

Get a curated subset of a Peer’s Representation. A Representation is always a subset of the total knowledge about the Peer. The subset can be scoped and filtered in various ways.

If a session_id is provided in the body, we get the Representation of the Peer scoped to that Session. If a target is provided, we get the Representation of the target from the perspective of the Peer. If no target is provided, we get the omniscient Honcho Representation of the Peer.

POST /v3/workspaces/{workspace_id}/peers/{peer_id}/representation

Get Representation

cURL

curl --request POST \
  --url https://api.honcho.dev/v3/workspaces/{workspace_id}/peers/{peer_id}/representation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "session_id": "<string>",
  "filters": {},
  "scope": "<string>",
  "target": "<string>",
  "search_query": "<string>",
  "search_top_k": 50,
  "search_max_distance": 0.5,
  "include_most_frequent": true,
  "max_conclusions": 25
}
'

200

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

peer_id · string · required

Body

application/json

Options for getting the peer representation

session_id · string | null

Optional session ID within which to scope the representation

filters · Filters · object | null

Optional filters to scope the representation. This endpoint supports only the 'session_id' key: a session id, a list of session ids, or {"in": [...]}. When session_id is also set, it must be included in the allowlist.

scope · string string[]

Optional (unprefixed) scope name(s) to confine the representation. A single scope reads the scope's own representation of the target peer, formed only from the scope's member sessions. A list of scopes restricts the representation to conclusions from the union of the scopes' member sessions (explicit allowlist, fail-closed: an empty union yields an empty representation). Mutually exclusive with filters and session_id. Requires a workspace- or admin-level key.

target · string | null

Optional peer ID to get the representation for, from the perspective of this peer

search_query · string | null

Optional input to curate the representation around semantic search results

search_top_k · integer | null

Only used if search_query is provided. 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. Maximum distance to search for semantically relevant conclusions

Required range: 0 <= x <= 1

include_most_frequent · boolean | null

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

max_conclusions · integer | null · default: 25

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

Required range: 1 <= x <= 100

Response

200

application/json

Successful Response

representation · string · required