---
title: "AI Risk Analyst"
method: POST
path: "/chat"
tags: ["Risk Metrics"]
---

# AI Risk Analyst

`POST /chat`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/chat`
- Auth: HTTP bearer

Natural language risk analysis with OpenAI tool calling against RiskModels data (DAL). LLM tokens are billed per the chat capability; each internal tool call is billed separately at the same rates as the corresponding REST endpoints (e.g. metrics-snapshot, ticker-returns). search_tickers is free. Returns tool_calls_summary and expanded _agent (llm_cost_usd, tool_cost_usd, tool_calls).

## Request body

- object
  - `messages` object[]
    - `role` 'user' | 'assistant', required
    - `content` string, required
  - `model` string: AI model to use (default gpt-4o-mini)
  - `response_mode` 'markdown' | 'catalog' | 'hybrid': Reserved for future streaming / A2UI modes; non-streaming JSON today.
  - `parallel_tool_calls` boolean: When false, sets OpenAI parallel_tool_calls to false. Omit or true for parallel tool execution on supported models (e.g. gpt-4o-mini).
  - `execute_tools_sequentially` boolean: When true, server executes tool calls sequentially instead of concurrently.
  - `workspace_tools` boolean: Offer the riskmodels.net workspace command-bus tools (set_subject / set_window) and emit their typed actions as distinct `action` SSE frames. Honored only when streaming (Accept: text/event-stream) — the frame is the delivery channel — and intended for the workspace-mounted portal chat, which validates actions client-side (fail-closed) before applying them.

## Response `200`

Assistant reply, accumulated token usage across tool rounds, optional tool_calls_summary, lineage metadata, and _agent cost breakdown (LLM + tools).

- object
  - `message` object
    - `role` 'assistant', required
    - `content` string, required
  - `model` string
  - `usage` object, nullable
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
  - `tool_calls_summary` ChatToolCallSummary[], nullable
    - `tool` string: OpenAI function name (e.g. get_risk_metrics).
    - `capability` string, nullable: Billing capability id, or null for free tools (e.g. search_tickers).
    - `cost_usd` number, float
    - `latency_ms` integer
    - `error` string, nullable
  - `_metadata` object
  - `_agent` AgentMeta: Per-request billing and telemetry metadata appended to metered responses.
    - `cost_usd` number, float: Cost deducted from prepaid balance for this request. 0 if served from cache.
    - `latency_ms` integer: Server processing time in milliseconds.
    - `request_id` string: Unique request identifier for support lookups.
    - `confidence` object
      - `overall` number, float
      - `factors` object
    - `data_freshness` string, date-time: ISO timestamp of the data's as-of datetime.
    - `billing_code` string: Internal billing classification for this request type.
    - `cache_status` 'HIT' | 'MISS' | 'BYPASS': Whether this response was served from cache.
    - `llm_cost_usd` number, float: POST /chat only: portion of cost from LLM token billing (estimated preflight charge).
    - `tool_cost_usd` number, float: POST /chat only; sum of internal data tool charges for this turn.
    - `tool_calls` integer: POST /chat only; number of tool invocations in this request.

## Other responses

- `400`: Invalid request body.
- `401`: Missing or invalid Bearer token.
- `402`: Insufficient balance.
- `429`: Rate limit exceeded.
- `502`: Upstream AI provider error.
- `503`: Chat not configured (e.g. missing MOONSHOT_API_KEY).

---

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