---
title: "Query the Brain"
method: POST
path: "/v1/chat"
tags: ["Brain"]
---

# Query the Brain

`POST /v1/chat`

## Request

- Base URL: `https://api.marketintell.ai`
- URL: `https://api.marketintell.ai/v1/chat`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Send a natural language query to the Brain agent. Supports streaming via SSE when stream=true.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `message` string, required: Natural language query
  - `session_id` string, uuid: Session ID for multi-turn conversations
  - `stream` boolean: Enable SSE streaming
  - `domain` 'crypto' | 'us_equities' | 'india_stocks': Force a specific domain. When omitted, the planner classifies the query (default: crypto).
  - `mode` 'auto' | 'deep': `'auto'` (default) lets the planner pick the T1/T2/T3 pipeline. `'deep'` forces the T3 supervisor (Pro+ only). The legacy value `'fast'` is no longer accepted by the API — use `'auto'` instead.
  - `portfolio_id` string: Inject a specific portfolio's context. Must be owned by the calling key — cross-owner ids are silently ignored.
  - `include_portfolio` boolean: When true (and no portfolio_id supplied), auto-inject the calling key's most-recently-updated portfolio.
  - `include_facts` boolean: When true, include the neutral fact projection in fact_projection and reasoning_summary.evidence. Recommended for autonomous agent consumers.
  - `response_format` object: Output format. Defaults to text (prose markdown). Use json_schema for structured JSON output, or the trade_setup shorthand to receive the versioned canonical trade-setup schema (equivalent to json_schema with name='trade_setup' and no inline schema).
    - `type` 'text' | 'json_schema' | 'trade_setup'
    - `json_schema` object
      - `name` string, required: Built-in schema name (trade_setup, market_analysis, token_screen) or custom name. When set to a built-in name with no inline schema, the server injects the built-in.
      - `schema` object: Custom JSON schema (optional if using built-in name)
      - `strict` boolean

## Response `200`

Brain response with classification and correlation metadata

- object
  - `success` boolean
  - `data` object
    - `contract_version` '1.0'
    - `execution_id` string: Stable request/execution correlation id
    - `status` 'completed'
    - `session_id` string, uuid
    - `content` string
    - `disclaimer` string: Financial-advice disclaimer. Always present. A separate field — never folded into `content` — so structured-output / json_schema replies stay clean. Clients should render it persistently alongside the answer.
    - `specialists_used` string[]
    - `latency_ms` number
    - `classification` object, nullable
      - `specialists` string[]
      - `tokens` string[]
      - `intent` string
    - `correlation` object, nullable
      - `alignment` 'BULLISH' | 'BEARISH' | 'NEUTRAL' | 'NO_EDGE'
      - `score` number
      - `confirming` string[]
      - `contradicting` string[]
      - `sizing_multiplier` number
      - `summary` string
    - `structured_output` object, nullable: Parsed JSON output when response_format.type is json_schema. Null when type is text.
    - `reasoning_summary` object: Safe evidence and decision summary. It does not expose hidden chain-of-thought or model scratchpads.
    - `provenance` object
    - `delivery` object
    - `recovery` object, nullable
    - `fact_projection` object: Present when include_facts=true.
    - `degradation` object

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit or daily quota exceeded

---

[API](https://skmtc.dev/marketintell/apis/marketintell-api.md) · [All operations](https://skmtc.dev/marketintell/apis/marketintell-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marketintell/apis/marketintell-api/revisions/f3ef87afc41f?raw)