---
title: "Terminal AI research agent"
method: POST
path: "/api/terminal/agent"
tags: ["terminal-agent"]
---

# Terminal AI research agent

`POST /api/terminal/agent`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/terminal/agent`
- Auth: API key in header `X-API-Key`

Drive the terminal's AI research assistant: a tool-calling loop over the
platform's own data (screening, filings, watchlist, portfolio). Restricted
to the internal plan; other keys receive 404 so the endpoint stays
invisible. Streams the assistant's turns back to the caller.

## Request body

- AgentRequest
  - `messages` AgentMessage[], required: Conversation so far (user/assistant turns).
    - `role` string, required
    - `content` string, required
  - `model` string, nullable: Override the reasoning model (else env default).
  - `max_turns` integer, nullable: Max tool-calling turns (1-10).

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: messages must contain at least one user/assistant turn
- `401`: API key required or invalid
- `404`: Not available for this API key's plan
- `422`: Validation Error
- `429`: Quota exceeded
- `503`: AI backend unavailable

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)