---
title: "Workspace Chat"
method: POST
path: "/v3/workspaces/{workspace_id}/chat"
tags: ["workspaces"]
---

# Workspace Chat

`POST /v3/workspaces/{workspace_id}/chat`

## Request

- Base URL: `https://api.honcho.dev`
- URL: `https://api.honcho.dev/v3/workspaces/{workspace_id}/chat`
- Auth: HTTP bearer

Query the entire workspace using natural language. Runs the Dialectic agent over every peer in the workspace rather than a single (observer, observed) pair: there is no anchor peer and no `target`.

Pass `session_id` to narrow message tools to one session, or `scope` to restrict recall to the union of the named scopes' member sessions (always an allowlist, even for a single name; a scope with no member sessions recalls nothing). `session_id` and `scope` are mutually exclusive.

Set `stream: true` to receive the answer as a `text/event-stream` of `{"delta": {"content": ...}, "done": false}` chunks terminated by `{"done": true}`. Requires a workspace- or admin-level key.

## Path parameters

- `workspace_id` string, required

## Request body

- WorkspaceChatOptions: Options for workspace-level chat (no anchor peer; see DialecticOptions).
  - `session_id` string, nullable: Optional session to scope message tools to
  - `query` string, required: Workspace chat prompt
  - `stream` boolean: Return the answer as a text/event-stream. The answer arrives when the agent finishes gathering context, usually as a single chunk; only an answer synthesized at the tool-call limit streams as it is generated.
  - `reasoning_level` 'minimal' | 'low' | 'medium' | 'high' | 'max': Level of reasoning to apply: minimal, low, medium, high, or max
  - `response_format` object, nullable: Optional JSON Schema (root type 'object') the response must conform to. When provided, `content` is a JSON string matching this schema.
  - `scope` union: Optional (unprefixed) scope name(s) restricting recall to the union of the scopes' member sessions (explicit allowlist, fail-closed: an empty union recalls nothing). Mutually exclusive with `session_id`. Requires a workspace- or admin-level key.
    - string
    - string[]
  - `include_evidence` boolean: When true, the response includes an `evidence` object listing the conclusions and messages the agent read while answering, plus the tool calls it made. Evidence is collated from what the agent accessed; the model is never asked to cite anything, so evidence may over-report (accessed is not the same as used).

## Response `200`

Successful Response

- object
  - `content` string, nullable, required
  - `evidence` Evidence: What the dialectic agent read and did while answering. Collated from the agent's own reads rather than reported by the model, so it is deterministic but over-reports: it lists what the agent accessed, which is not necessarily what the answer relied on. Meant for auditing and analytics -- inspecting why an answer looks the way it does, or measuring what recall actually reaches the agent. It is not a read API: conclusions carry their text because that text is the thing being audited and the deriver keeps it short, while messages carry identity alone (see `EvidenceMessageRef`).
    - `conclusions` EvidenceObservation[]: Conclusions the agent read, whether prefetched or found via its tools
      - `id` string, required: Conclusion (document) ID
      - `level` 'explicit' | 'deductive' | 'inductive' | 'contradiction', required: Conclusion level: explicit, deductive, inductive, or contradiction
      - `content` string, required: The conclusion text (the derived conclusion, for non-explicit levels)
      - `created_at` string, date-time, required: When the conclusion was derived, from its source messages when known
      - `session_id` string, nullable: Session the conclusion is scoped to, if any
      - `observer_id` string, required: The peer who made the conclusion
      - `observed_id` string, required: The peer the conclusion is about
      - `source_ids` string[]: IDs of the conclusions this one was derived from. Empty for explicit conclusions, which derive from messages rather than from other conclusions.
    - `messages` EvidenceMessageRef[]: Messages the agent read via its search and grep tools, by ID and provenance only. Fetch a message to read its content.
      - `id` string, required: Message ID
      - `session_id` string, required: Session the message belongs to
      - `peer_id` string, required: Peer who sent the message
      - `created_at` string, date-time, required: When the message was sent
    - `tool_calls` EvidenceToolCall[]: Tools the agent invoked, in order, with their arguments. Results are omitted (they are reflected in `conclusions` and `messages`), and so are calls that failed, so this is a record of successful invocations rather than a complete reasoning trace.
      - `tool_name` string, required: Name of the tool
      - `tool_input` object: Arguments the agent passed to the tool
    - `reasoning_trace_id` string, nullable: ID of the stored reasoning trace for this call, when trace storage is enabled

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-22** (v3) `709fb0271696`: 2 info
  - added the required property `evidence/anyOf[subschema #1: Evidence]/conclusions/items/observed_id` to the response with the `200` status
  - added the required property `evidence/anyOf[subschema #1: Evidence]/conclusions/items/observer_id` to the response with the `200` status
- **2026-09-14** (v3) `1c66cf22809c`: 2 info
  - added the new optional request property `include_evidence`
  - added the optional property `evidence` to the response with the `200` status
- **2026-09-08** (v3) `d393a0e437ca`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/plastic-labs/apis/honcho-api/changes/v3/workspaces/:workspace_id/chat/post.md)

---

[API](https://skmtc.dev/plastic-labs/apis/honcho-api.md) - [All operations](https://skmtc.dev/plastic-labs/apis/honcho-api/llms.txt) - [OpenAPI document](https://skmtc.dev/plastic-labs/apis/honcho-api/revisions/11f51f4d683e?raw)