MINARAHTTP API
Every route exposed by the gateway (`npm run serve`)
The HTTP gateway (npm run serve) exposes the same agent behind a REST/SSE API. Every route lives on version-prefixed /v1/..., except the unauthenticated /healthz liveness probe.
Authentication
Set GATEWAY_AUTH_TOKEN in the environment to require a bearer token on every /v1/... route. If unset, the gateway accepts all requests (use only for local development).
Authorization: Bearer <GATEWAY_AUTH_TOKEN>Health
| Method | Path | Description |
|---|---|---|
GET | /healthz | Liveness probe. Returns 200 with \{"ok": true\} if the gateway is up. |
GET | /v1/healthz | Versioned mirror of /healthz. Returns \{"ok": true, "ts": ...\} without auth s… |
Chat
| Method | Path | Description |
|---|---|---|
POST | /v1/chat/stream | Starts an agent turn and returns immediately with the session id. The turn runs … |
POST | /v1/assist/system-prompt | Streams a Custom Agent system prompt for the Web UI wizard's Generate-with-AI pa… |
POST | /v1/chat/interject | Queue a steering message for the session's in-flight turn. The gateway injects i… |
POST | /v1/chat/interrupt | Stop the session's in-flight turn. The turn ends gracefully: partial work is kep… |
GET | /v1/chat/recommendation | Long-polls the per-session feature-recommendation store for the card computed as… |
GET | /v1/chat/sessions/:id/goal | Return the session's standing goal, or null when none is set. The agent pursue… |
POST | /v1/chat/sessions/:id/goal | Set a standing goal for the session. Rejected with 400 when a goal is already ac… |
POST | /v1/chat/sessions/:id/goal/pause | Pause the standing goal's continuation. Manual turns still work; the goal can be… |
POST | /v1/chat/sessions/:id/goal/resume | Resume a paused goal. Resets the turn budget so the goal gets a fresh run of tur… |
POST | /v1/chat/sessions/:id/goal/clear | Clear the standing goal. Terminal — the goal is gone. |
POST | /v1/chat/sessions/:id/goal/subgoals | Append an acceptance criterion to the standing goal. The judge and the next-turn… |
DELETE | /v1/chat/sessions/:id/goal/subgoals/:n | Remove the acceptance criterion at position n (1-based). Rejected with 400 whe… |
Chat sessions
| Method | Path | Description |
|---|---|---|
GET | /v1/sessions/:parentId/subagent-runs/:childSessionId | Return the folded transcript for one synchronous subagent delegation. The chil… |
GET | /v1/sessions | List the user's chat sessions with last-activity timestamp and message count, mo… |
GET | /v1/sessions/search | Search message content across every session, best match first (SQLite FTS5, bm25… |
POST | /v1/sessions | Provision a new session id; the agent loop scopes per-session state (frozen snap… |
GET | /v1/sessions/:id | The primary history-read endpoint: session metadata + every persisted message in… |
POST | /v1/sessions/:id/completion/read | Idempotently acknowledge the latest completed or failed agent turn for a session… |
DELETE | /v1/sessions/:id | Delete a session and all of its messages (and the session's on-disk workspace). … |
PATCH | /v1/sessions/:id | Set the session's title. A manual rename wins over the background LLM-generated … |
GET | /v1/institution/sessions/:sessionId/pipeline | Returns the session-owned pipeline, the latest run snapshot fallback, or the def… |
PUT | /v1/institution/sessions/:sessionId/pipeline | Validates and saves a session-owned pipeline using optimistic revision control. |
GET | /v1/institution/sessions/:sessionId/runs | Returns chronological immutable Roundtable snapshots, final results, and report … |
State & control
| Method | Path | Description |
|---|---|---|
GET | /v1/sync/status | Returns the current sync mode plus each direction's watermark, last run time, an… |
POST | /v1/sync/run | Runs one exchange with the account immediately: pulls remote changes, pushes loc… |
GET | /v1/sync/domains | Domains this install can mirror, so a peer skips one this deployment lacks inste… |
GET | /v1/sync/:domain/changes | Entities a mirroring peer has not seen, tombstones included — a deletion is read… |
POST | /v1/sync/:domain/ingest | Idempotent upsert keyed on the entity id, which the writing side owns and must n… |
GET | /v1/sync/:domain/:entityId/items | A page of an entity's children, oldest-first so a page replays in order — conver… |
GET | /v1/status | Kill switch state, daily spend, tool count, review engine state. Equivalent to t… |
GET | /v1/system-metrics | Process + system snapshot for the Dashboard System status row: CPU percent, memo… |
GET | /v1/dashboard/achievements | Marketing-style stats for the web-ui Dashboard banner: activation timestamp, nat… |
GET | /v1/portfolio | Current portfolio snapshot from the Minara backend, formatted for agent consumpt… |
GET | /v1/methodologies | List of registered methodologies with their pass/fail counts and recent outcomes… |
GET | /v1/learning/audit/reports | Trend + history of methodology audit health reports. Query days (default 30) b… |
GET | /v1/learning/audit/reports/latest | The most recent methodology audit report in full: composite health score, per-di… |
GET | /v1/learning/audit/reports/:passId | One methodology audit report in full, looked up by its pass id. |
POST | /v1/learning/audit/run | Run one audit pass on demand and persist it. Optional body \{ windowDays \} (cla… |
POST | /v1/kill | Blocks all tier ≥ 2 tool calls until /v1/unkill is called. Intended for emerge… |
POST | /v1/unkill | Clears the kill switch flag. |
POST | /v1/interactions/:id/answer | Resolve a pending question the agent asked mid-turn. Questions arrive on the WS … |
Portfolio
| Method | Path | Description |
|---|---|---|
GET | /v1/portfolio/status | Quick readiness probe: whether Minara is authenticated and which venues are reac… |
GET | /v1/portfolio/spot | Aggregate spot balances across every connected wallet, normalized to the gateway… |
GET | /v1/portfolio/spot/snapshot | Stable-asset balances and non-stable positions from one authenticated Minara P&L… |
GET | /v1/portfolio/spot/positions | Per-asset spot positions including avg cost basis when known. |
GET | /v1/portfolio/perps | Open perp positions across every Minara perp sub-wallet. Use ?subAccountId= to… |
GET | /v1/portfolio/perps/summary | Aggregated equity / margin / unrealized PnL across perp subs. |
GET | /v1/portfolio/history | Timeseries of total portfolio value bucketed for chart display. |
GET | /v1/portfolio/spot/activity | Cross-chain spot activity feed (swaps + transfers) for the user's primary wallet… |
GET | /v1/tx/status | Poll a single transaction's on-chain status by its transaction id. Wraps Minara … |
Perps
| Method | Path | Description |
|---|---|---|
GET | /v1/perps/account-state | Live state for one Hyperliquid sub: equity, margin usage, withdrawable, open ord… |
GET | /v1/perps/sub-accounts | All perp sub-wallets under the user's Minara perp wallet, with the multi-exchang… |
GET | /v1/perp-wallets | Same handler as /v1/perps/sub-accounts; aligned with the upstream OpenAPI path… |
POST | /v1/perp-wallets | Create a new perp sub-account bound to one exchange (hyperliquid |
POST | /v1/perps/sub-accounts | Agent-native alias of POST /v1/perp-wallets. Same body, same response shape. |
POST | /v1/perp-wallets/rename | Rename an existing perp sub-account. Body: \{ subAccountId: string, name: string… |
POST | /v1/perps/sub-accounts/rename | Agent-native alias of POST /v1/perp-wallets/rename. |
POST | /v1/trading-gateway/place-orders | Batch place perp orders against the sub-account's bound exchange. Each order use… |
POST | /v1/trading-gateway/cancel-orders | Batch cancel by \{ symbol, orderId \}. Body: \{ cancels: \{ symbol: string, order… |
POST | /v1/trading-gateway/modify-order | Modify an active order's price, quantity, or trigger price. Body: \{ symbol: str… |
POST | /v1/trading-gateway/update-leverage | Change leverage and margin mode (cross vs isolated) on a symbol in one round-tri… |
POST | /v1/trading-gateway/update-isolated-margin | Adjust the isolated-margin amount on an existing position. Body: \{ symbol: stri… |
POST | /v1/trading-gateway/withdraw | Withdraw USDC to an external address. Body: \{ amount: string, toAddress: string… |
GET | /v1/trading-gateway/summary | One-shot read for a single sub-wallet's equity, open positions, and open orders.… |
GET | /v1/wallet/deposits | One envelope with spot + perps deposit addresses. Spot maps from the user's cros… |
GET | /v1/wallet/supported-chains | Proxy of the upstream Minara /tokens/supported-chains endpoint. Returns the li… |
POST | /v1/wallet/withdraw/spot | Preview a cross-chain spot withdraw (confirm: false) or execute it (confirm: … |
POST | /v1/wallet/withdraw/perps | Preview a perps USDC/Arbitrum withdraw (confirm: false) or execute it (confir… |
GET | /v1/wallet/withdrawals/{operationId} | Durable status lookup for a withdraw operation. Returns the latest known \{opera… |
GET | /v1/perps/copilot-history | Returns recent read-only Copilot price recommendations for a perp symbol. When t… |
POST | /v1/perps/copilot-analysis | Requests a read-only Copilot price recommendation for a perp symbol. This endpoi… |
GET | /v1/perps/trades | Hyperliquid fill history for one sub-wallet (live, not the local mirror). Mirror… |
GET | /v1/perps/funding | Funding payments received / paid per perp position. |
GET | /v1/perps/transfers | Wallet-scoped Hyperliquid deposits, withdrawals, and account transfers from the … |
GET | /v1/perps/order-history | Recently filled / cancelled orders. |
GET | /v1/perps/lighter-pnl | Rolling realized PnL for a Lighter sub-wallet, fetched from Lighter's first-clas… |
GET | /v1/orders | Return resting perps orders, or conditional spot orders with source=spot. |
POST | /v1/perps/transfer | Move idle USDC from one perp sub-wallet to another. USDC only. Fund-moving: prev… |
POST | /v1/perps/deposit | Deposit at least 10 USDC from a selected Spot holding into a perp sub-wallet. Th… |
GET | /v1/perps/sub-account/:subAccountId/idle-usdc | The single 'available to transfer' number for a perp sub-wallet: idle USDC after… |
Autopilot
| Method | Path | Description |
|---|---|---|
GET | /v1/autopilot/managed/catalog | List the managed (fully-managed) strategy types the picker can offer — Sharpe Gu… |
GET | /v1/autopilot/managed/catalog/:strategyType/backtest | Backtest preview for one managed strategy type (equity curve + headline stats). … |
GET | /v1/autopilot/managed/strategies | Every managed strategy with its bound sub-account and normalized status. The /au… |
GET | /v1/autopilot/managed/aggregated-summary | Single aggregate source shared by the /autopilot KPI bar and the Dashboard manag… |
GET | /v1/autopilot/managed/xstrategy/deployments | Lists the user's live XStrategy deployments (any status) so the Autopilot strate… |
GET | /v1/autopilot/managed/xstrategy/backtest/:backtestId | Full multi-asset backtest report for a deployment (add /curves for the equity … |
GET | /v1/autopilot/managed/by-sub-account/:subAccountId | Per-sub-account snapshot the detail panel consumes: the bound strategy (or null)… |
POST | /v1/autopilot/managed/strategies | Create a managed strategy on a sub-wallet. Fund-moving: omit confirm (or pass … |
POST | /v1/autopilot/managed/run | Run a strategy from another source as autopilot. marketplace subscribes the pu… |
POST | /v1/autopilot/managed/:strategyId/disable | Stop a running managed strategy. Fund-affecting, so it follows the same preview … |
POST | /v1/autopilot/managed/xstrategy/:strategyId/stop | Stop a live XStrategy deployment the user authored (Autopilot surfaces it alongs… |
POST | /v1/autopilot/managed/xstrategy/:strategyId/deploy | Deploy an XStrategy onto the selected sub-wallet by cloning the existing deploym… |
Market data
| Method | Path | Description |
|---|---|---|
GET | /v1/quote/batch | Quotes for up to 25 symbols in one round trip. mode=compact skips fundamentals… |
GET | /v1/quote/:ticker | Spot price + 24h change + traditional metrics (P/E, EPS, dividend yield, 52-week… |
GET | /v1/quote/crypto/:symbol | Market cap, FDV, 24h volume (USD), 24h % change, name, logo, and chain for one c… |
GET | /v1/market/candles | OHLC bars for one symbol + interval. Address-scoped on-chain spot requests use M… |
GET | /v1/market/perps-price | Returns the current perpetual-market price and venue-specific market identifiers… |
GET | /v1/market/sparkline | Compact close-only series for inline sparkline rendering in the web UI. |
GET | /v1/market/trending | Returns normalized trending crypto and stock rows for the Workbench asset switch… |
GET | /v1/market/search | Fuzzy-match ticker symbols + names across crypto, stocks, ETFs, commodities, for… |
GET | /v1/markets/movers | Biggest movers for the markets overview board. class=stocks (default) returns … |
GET | /v1/markets/snapshot | Legacy-compatible aggregate of major index quotes (with intraday sparklines), co… |
GET | /v1/markets/indices | Major US stock index quotes and intraday series. Cached for 30 seconds. |
GET | /v1/markets/futures | Gold, crude-oil, and natural-gas futures. Cached for 30 seconds. |
GET | /v1/markets/forex | Major foreign-exchange pair quotes. Cached for 30 seconds. |
GET | /v1/markets/treasury | US Treasury yields from 13 weeks through 30 years. Cached for 30 seconds. |
GET | /v1/markets/crypto/quotes | BTC, ETH, SOL, XRP, and DOGE spot quote seeds with public-stream mappings. Cache… |
GET | /v1/markets/fear-greed | Crypto Fear and Greed reading. Cached for 60 seconds. |
GET | /v1/markets/sectors | Daily performance of the 11 GICS sectors for the board's heatmap, proxied by the… |
GET | /v1/markets/news | A market headline feed for the board, parsed from Yahoo Finance's keyless RSS. ``… |
GET | /v1/markets/asset-news | Paginated news for one stock, crypto asset, or forex pair. Proxied from Minara's… |
GET | /v1/markets/asset-info | Normalized information for the asset detail Info, Team, and Funding tabs. Stocks… |
GET | /v1/markets/calendar | The next session's earnings reports from Nasdaq's keyless calendar, forward-fill… |
Voice
| Method | Path | Description |
|---|---|---|
GET | /v1/voice/status | Whether speech services are configured: stt_configured (a transcription provid… |
POST | /v1/voice/realtime/session | Exchange a browser-generated WebRTC SDP offer for an OpenAI SDP answer. scenari… |
GET | /v1/voice/voices | The voice-picker option list: official preset voices (ElevenLabs + OpenAI, alway… |
GET | /v1/voice/settings | Current user-tunable speech-synthesis settings. Pass provider=openai for voice… |
PUT | /v1/voice/settings | Persist user-tuned speech-synthesis settings. Pass provider=openai or provide… |
POST | /v1/voice/cleanup | Delete persisted voice audio (spoken replies + mic recordings) on chat messages … |
POST | /v1/voice/transcribe | Transcribe an uploaded audio recording via the configured voice provider (Eleven… |
POST | /v1/voice/tts | Stream synthesized speech for up to 4096 chars of text. The provider body is pip… |
POST | /v1/sessions/:id/voice-audio | Attach a previously-uploaded audio file (POST /v1/files) to an assistant message… |
Image & video
| Method | Path | Description |
|---|---|---|
GET | /v1/media/settings | Returns Fal.ai connection status and the independently selected image and video … |
PUT | /v1/media/settings | Selects the Fal.ai authentication method or the default image and video endpoint… |
GET | /v1/media/models | Lists active Fal.ai endpoints for one output modality, including dynamically inf… |
POST | /v1/media/models/refresh | Bypasses the five-minute catalog cache for one or both output modalities. |
GET | /v1/media/models/schema | Returns the resolved OpenAPI input and output schema, field order, and inferred … |
POST | /v1/media/providers/fal/oauth/init | Starts the Fal.ai device flow and returns the user code and verification URL. Th… |
GET | /v1/media/providers/fal/oauth/poll | Polls a device flow. A successful response stores refreshable OAuth credentials … |
POST | /v1/media/providers/fal/api-key | Validates and stores a Fal.ai API key in the structured credential store, then s… |
DELETE | /v1/media/providers/fal/auth/:kind | Removes either the saved Fal.ai sign-in profile or API-key override. The other m… |
Files & artifacts
| Method | Path | Description |
|---|---|---|
POST | /v1/files | Upload a file into the sandboxed workspace. Returns a key that can be referenced… |
GET | /v1/files/:key | Stream a previously-uploaded sandboxed file back to the caller. |
GET | /v1/artifacts/:id | Fetch an agent-generated artifact (chart, spreadsheet, report payload) by its id… |
GET | /v1/artifacts | List completed report artifacts for the web UI's Files pages. Filter by kind=ch… |
DELETE | /v1/artifacts | Permanently delete one to 200 archived report artifacts and their files. Every a… |
GET | /v1/sandbox/files/:name | Read a file the agent wrote into its per-session sandbox. Cannot escape the sand… |
Workspace files
| Method | Path | Description |
|---|---|---|
GET | /v1/workspace/files | Enumerate every editable workspace md file with size, mtime, and sha256. Files t… |
GET | /v1/workspace/files/:name | Return the contents of a single workspace md file plus its sha256. :name must … |
PUT | /v1/workspace/files/:name | Atomically replace a workspace md file. expected_sha256 is REQUIRED — pass the… |
POST | /v1/workspace/files/:name/restore-template | Overwrite the workspace file with the shipped template from src/workspace/templ… |
Research
| Method | Path | Description |
|---|---|---|
POST | /v1/research | Run the deep-research pipeline directly from the gateway without going through t… |
POST | /v1/factors/research-brief-suggestions | Generates four editable time-series factor research goals for the selected angle… |
POST | /v1/factors/research-configurations/generate | Converts compact research inputs into a reviewable, deterministic configuration … |
GET | /v1/factors/campaigns | Lists durable time-series factor research campaigns, newest first. |
POST | /v1/factors/campaigns | Creates a bounded, durable factor research campaign from a complete FactorResear… |
GET | /v1/factors/tasks | Lists logical research tasks. Retry and direction-change rounds are grouped into… |
GET | /v1/factors/tasks/:id | Returns the task summary, current campaign round, immutable round history, and a… |
DELETE | /v1/factors/tasks/:id | Deletes all campaign rounds belonging to a logical research task. Running rounds… |
GET | /v1/factors/tasks/:id/rounds | Lists the immutable campaign rounds that belong to one research task. |
POST | /v1/factors/tasks/:id/rounds | Creates a new round in the same task with a new search direction and prior rejec… |
POST | /v1/factors/tasks/:id/direction-decisions | Records a strategy direction at a task checkpoint and creates the next round wit… |
GET | /v1/factors/tasks/:id/agent-messages | Returns persisted read-only Agent output across all rounds in a research task. |
GET | /v1/factors/tasks/:id/events | Replays and tails durable events for the task's current round as Server-Sent Eve… |
GET | /v1/factors/campaigns/:id | Returns the frozen research spec, stage, progress, budgets, Pareto ids, and stop… |
POST | /v1/factors/campaigns/:id/pause | Pauses a durable factor research campaign idempotently. |
POST | /v1/factors/campaigns/:id/resume | Resumes a durable factor research campaign idempotently. |
POST | /v1/factors/campaigns/:id/cancel | Cancels a durable factor research campaign idempotently. |
POST | /v1/factors/campaigns/:id/extend-budget | Raises absolute campaign limits with an audited reason and resumes a budget-paus… |
POST | /v1/factors/campaigns/:id/fork | Creates a traceable revision from a paused or completed campaign with revised re… |
GET | /v1/factors/campaigns/:id/events | Replays and tails durable campaign events as Server-Sent Events. |
GET | /v1/factors/candidate-decisions | Lists deterministic PASS or REJECT decisions with task, round, evaluator metrics… |
POST | /v1/factors/candidate-decisions/:id/override | Appends an auditable manual exception without replacing the original automatic P… |
GET | /v1/factors/candidates | Lists candidates in a campaign, optionally filtered by lifecycle status. |
GET | /v1/factors/candidates/:id | Returns a candidate's normalized DSL, hypothesis, lineage, required fields, and … |
POST | /v1/factors/candidates/:id/approve | Creates an immutable approved Factor Version after a completed sealed audit. |
POST | /v1/factors/candidates/:id/reject | Records a human rejection and an immutable rejected Factor Version. |
GET | /v1/factors/library | Lists approved Factor Versions with cursor pagination; archived versions are opt… |
GET | /v1/factors/library/:id/versions | Lists every immutable version for one stable factor id. |
GET | /v1/factors/library/:id/versions/:version | Returns one immutable factor definition and its complete research provenance. |
POST | /v1/factors/library/:id/versions/:version/archive | Prevents new strategies from selecting an approved factor version while preservi… |
GET | /v1/factors/objective-profiles | Lists versioned optimization objective profiles available to new campaigns. |
POST | /v1/factors/objective-profiles | Stores a new immutable version of optimization objective profile. |
GET | /v1/factors/stopping-policies | Lists versioned stopping policies available to new campaigns. |
POST | /v1/factors/stopping-policies | Stores a new immutable version of stopping policy. |
GET | /v1/factors/evaluation-profiles | Lists deterministic, versioned evaluator chains and hard quality gates. |
GET | /v1/factors/evaluation-algorithms | Lists the fixed deterministic evaluator configurations available for qualificati… |
GET | /v1/factors/evaluation-algorithm-configurations | Lists built-in and owner-scoped immutable algorithm configuration versions. |
POST | /v1/factors/evaluation-algorithm-configurations | Creates an immutable owner-scoped configuration from fixed evaluator modules. Ar… |
GET | /v1/factors/evaluation-algorithm-configurations/:id/versions | Lists immutable versions for one evaluation algorithm configuration. |
POST | /v1/factors/evaluation-algorithm-configurations/:id/versions/:version/archive | Archives a custom configuration for new research while preserving historical eva… |
POST | /v1/factors/evaluation-runs | Re-evaluates existing candidates against frozen snapshot data and fold plans wit… |
GET | /v1/factors/evaluation-runs/:id | Returns one immutable evaluation round and its independently versioned reports. |
GET | /v1/factors/candidates/:id/evaluation-runs | Lists original and subsequent evaluation rounds for one factor candidate. |
GET | /v1/factors/data-profiles | Lists provider capabilities, PIT guarantees, fields, frequencies, and asset cove… |
GET | /v1/factors/data-sources | Lists provider, evidence, dataset, profile, category, and selection state once p… |
PATCH | /v1/factors/data-sources/{sourceId}/preference | Updates calculation and research-evidence selection for one source used by new c… |
GET | /v1/factors/metrics | Lists the Metric Catalog used by Web, CLI, REPL, objectives, stopping conditions… |
GET | /v1/factors/metrics/:id | Returns one metric's label key, concise tooltip key, direction, unit, scopes, an… |
GET | /v1/institution/skills | Lists environment-available skills and the read-only tools eligible for Roundtab… |
GET | /v1/institution/agent-templates | Lists built-in and user-created templates for configuring one Roundtable agent. |
POST | /v1/institution/agent-templates | Saves an independent reusable agent configuration. |
PATCH | /v1/institution/agent-templates/:templateId | Updates a user-created agent template. Built-in templates are immutable. |
DELETE | /v1/institution/agent-templates/:templateId | Deletes a user-created agent template without changing existing Roundtable copie… |
GET | /v1/institution/roundtable-templates | Lists the default and user-created full Roundtable templates. |
POST | /v1/institution/roundtable-templates | Saves a titled, described, self-contained phase and agent configuration. |
PATCH | /v1/institution/roundtable-templates/:templateId | Updates a user-created Roundtable title, description, or configuration. |
DELETE | /v1/institution/roundtable-templates/:templateId | Deletes a user-created template without changing sessions or run snapshots that … |
GET | /v1/institution/runs/:runId/snapshot | Returns the immutable template, pipeline, agent settings, usage, and final resul… |
Personalization & memory
| Method | Path | Description |
|---|---|---|
GET | /v1/profile | Read the rebuilt personalization snapshot the agent injects into every system pr… |
GET | /v1/profile/onboarding | Whether the user has completed onboarding, plus their raw saved answers. Used by… |
POST | /v1/profile/onboarding | Apply onboarding answers: maps finance knowledge / frequency / risk / markets to… |
GET | /v1/financial-profile | Latest persisted financial_profile row: rebuilt platform wallet summary (compo… |
PUT | /v1/profile/prompt | Replace the user's custom system-prompt addendum (max 2000 chars). Surfaces in t… |
DELETE | /v1/profile/prompt | Drop the addendum. UI surfaces a hard-confirm before calling. |
PUT | /v1/profile/tags/:name | Set or clear one of the 11 behavioural-tag dimensions (e.g. risk, markets, ``… |
DELETE | /v1/profile/tags/:name | Equivalent to PUT with value: null — the tag is cleared and the agent re-infer… |
GET | /v1/memory | Read recent memories filtered by category, or run a hybrid (BM25 + vector) sea… |
GET | /v1/memory/trading-cases | Legacy free-form notes feed (memories table where category = 'trading-cases').… |
GET | /v1/memory/research-cases | Memories from /research runs filtered by topic. Used by the Research retrosp… |
POST | /v1/memory | Hand-write a memory the agent should always remember. Server stamps category=pe… |
PATCH | /v1/memory/:id | Edit statement, fact_type, or tickers on a source=user_manual memory. Ot… |
DELETE | /v1/memory/:id | Mark deleted_at = now(). Read paths (FTS, listings, snapshot) filter the row o… |
POST | /v1/memory/:id/restore | Clears deleted_at. Wired to the web-UI undo toast (5 second window) but works … |
POST | /v1/profile/refresh | Run all three personalization rebuilds (trading_summary / tags / memories) with … |
GET | /v1/profile/trade-history-breakdown | Three-source breakdown feeding the Financial Profile dashboard: local trade_hist… |
GET | /v1/profile/reference-wallets | User's watchlist of external wallet addresses. |
PUT | /v1/profile/reference-wallets | Replace the watchlist atomically. Server validates EVM (0x + 40 hex) and Solan… |
Learned preferences
| Method | Path | Description |
|---|---|---|
GET | /v1/learned-preferences | Inferred behavioural preferences awaiting your call (proposed / active / depreca… |
POST | /v1/learned-preferences/:id/:action | Transition one learned preference. Approve makes it active and brings it into th… |
GET | /v1/learned-preferences/:id | Full record for one learned preference id (description, signal strength, history… |
GET | /v1/watchlist | User-curated symbol watchlist persisted on the profile. |
PUT | /v1/watchlist | Replace the watchlist (max 100 symbols). |
GET | /v1/runtime-preferences | Returns the sub-feature toggle schema, current overrides, and the resolved value… |
PUT | /v1/runtime-preferences | Batch apply user overrides with all-or-nothing validation. Supports If-Match con… |
GET | /v1/runtime-preferences/critical-unlock-status | Read whether critical-tier toggles are currently unlocked (via the CLI minara c… |
POST | /v1/runtime-preferences/critical-unlock | Issue a short-lived unlock that lets a subsequent PUT /v1/runtime-preferences fl… |
POST | /v1/runtime-preferences/sign-ack | Mint a short-lived signed ack token consumed by the next PUT /v1/runtime-prefere… |
GET | /v1/credentials/families | Returns the provider-family registry (web search, market data, embeddings, cloud… |
PUT | /v1/credentials/families/:id | Writes overrides for a single provider family into the dataSources slot of ~/… |
DELETE | /v1/credentials/families/:id/field/:envVar | Remove a single field's override (reverts to env-derived fallback). |
GET | /v1/credentials/secrets | Returns every configured credential key across the flat credential slots (dataS… |
PUT | /v1/credentials/secrets/:key | Store a value under an UPPER_SNAKE key. Messaging env-vars are routed to the mes… |
GET | /v1/credentials/custom | Returns every key in the freeform custom slot of ~/.minara/credentials.json … |
PUT | /v1/credentials/custom/:key | Store a value under any freeform key in the custom slot (atomic + file-locked)… |
DELETE | /v1/credentials/custom/:key | Remove a single key from the custom slot. |
Notifications
| Method | Path | Description |
|---|---|---|
GET | /v1/notifications | Recent in-app notifications (newest first) plus an unread_count. A notificatio… |
DELETE | /v1/notifications | Delete every notification. Returns \{ ok, cleared \}. |
POST | /v1/notifications/read-all | Mark every unread notification as read. Returns \{ ok, updated \}. |
POST | /v1/notifications/:id/read | Mark a single notification read (idempotent). Returns \{ ok: true, updated \} — … |
DELETE | /v1/notifications/:id | Delete a single notification by id. |
Learning & methodology
| Method | Path | Description |
|---|---|---|
GET | /v1/memory/trading-cases/stats | 4-number snapshot for the Trading-cases dashboard: total cases, last 30 days, wi… |
GET | /v1/memory/trading-cases/methodology-trend | Per-week timeseries of outcome_alpha_return for the top-N methodologies over t… |
GET | /v1/memory/methodologies | Top-N methodologies ranked by Wilson-lower confidence, with case count, asset cl… |
GET | /v1/memory/methodology-cases | Read the unified methodology_observations ledger. Powers the audit ledger draw… |
GET | /v1/memory/trading-cases/:id | Full row JSON for one methodology_observations.id. Used by the right-side Draw… |
GET | /v1/memory/trades | Recent agent-executed trades from unified trade_executions: action, the from/t… |
GET | /v1/memory/strategy-runs | The user's autopilot / managed strategy runs from strategy_runs: name, creator… |
GET | /v1/memory/facts | FactLayer rows filtered by fact_type (observation.* / preference.* / goal.targ… |
Skills
| Method | Path | Description |
|---|---|---|
GET | /v1/skills | Every registered domain skill the agent can activate. Each entry carries activat… |
POST | /v1/skills/reload | Re-mirror vendored external skill packages into the sandbox and re-register them… |
Stats
| Method | Path | Description |
|---|---|---|
GET | /v1/stats | Token + cost + tool-call counters bucketed by chat session. |
POST | /v1/telemetry/block-action | Fire-and-forget click record for a ui_block event (UBP v1). Posted by the web-… |
LLM provider
| Method | Path | Description |
|---|---|---|
GET | /v1/llm/default-model | The model id the agent loop currently uses for new turns. |
PUT | /v1/llm/default-model | Switch the agent loop to a different model id. Validated against the live avail… |
GET | /v1/llm/available-models | Models the gateway can dispatch to, grouped by provider. Reflects the user's act… |
POST | /v1/llm/available-models/refresh | Force a live re-fetch of the active provider's model catalog, bypassing the in-m… |
GET | /v1/llm/background-models | Return whether background task models are supported and effective, the configura… |
PUT | /v1/llm/background-models | Turn background task models on or off, and assign models to titles, compression,… |
GET | /v1/shortcut-questions | Hand-authored fixed lists plus LLM-generated dynamic questions per category, use… |
Theme
| Method | Path | Description |
|---|---|---|
GET | /v1/theme | Web-UI theme preference (light/dark/system + accent). |
POST | /v1/theme | Update the persisted theme preference. |
GET | /v1/settings/report-design | Return the persisted visual settings used by Institution and Deep Research HTML/… |
PUT | /v1/settings/report-design | Normalize and persist the visual settings used by Institution and Deep Research … |
GET | /v1/report-style | Return the complete report-style configuration shared by Institution and Deep Re… |
PUT | /v1/report-style | Update report design settings and/or custom REPORT.css in one request. Settings … |
PUT | /v1/report-style/preset | Apply one of the built-in report style presets while preserving the remaining de… |
PUT | /v1/report-style/css | Validate and replace the custom REPORT.css applied after the selected preset and… |
Gateway
| Method | Path | Description |
|---|---|---|
POST | /v1/confidential-code/upload-sessions | Starts the browser-side TEE upload handshake used by Strategy Studio and X Strat… |
GET | /v1/gateway/providers | Inbound messaging providers registered with the gateway (Slack, Lark, etc). |
POST | /v1/gateway/providers/:id/fields/:envVar/reveal | Return the plaintext value of a single masked credential field (e.g. TELEGRAM_B… |
POST | /v1/gateway/providers/:id/resolve-chat-id | Look up the chat id the configured bot should send to, using the token the gatew… |
POST | /v1/gateway/providers/:id/oauth/init | Begin a Google OAuth consent flow for an OAuth-style messaging provider (email-… |
GET | /studio/p/:pageId | Serve a generated Data Studio dashboard as a standalone HTML page on its own lin… |
Migrate
| Method | Path | Description |
|---|---|---|
GET | /v1/migrate/manifest | List the data sets that can be exported (memories, profile, prefs, workflows). P… |
POST | /v1/migrate/export | Bundle the requested manifest entries into a portable JSON blob for backup / mig… |
POST | /v1/migrate/import | Restore from a previously exported bundle. Idempotent on stable ids (memories, p… |
Admin
| Method | Path | Description |
|---|---|---|
GET | /v1/admin/script-risk/decisions | Audit log of the script-risk gate's decisions in front of execute_code / term… |
GET | /v1/admin/script-risk/decisions/:id | Full audit record for one script-risk gate decision. |
GET | /v1/consent/grants | List authoring-time consent grants for Tier-3 / Tier-4 tools running from cron /… |
POST | /v1/consent/grants | Record operator authorization for a Tier-3 / Tier-4 tool call scheduled to run f… |
GET | /v1/consent/grants/:id | Return the full record for one consent grant. |
DELETE | /v1/consent/grants/:id | Mark a grant revoked. Subsequent autonomous calls to the tool under the same sco… |
POST | /v1/consent/grants/requirements | Dry-run scan of a draft cron / workflow / agent definition for Tier-3 / Tier-4 t… |
Config
| Method | Path | Description |
|---|---|---|
GET | /v1/config/financial-profile | Debug endpoint. Returns the effective FinancialProfileConfig currently loaded … |
GET | /v1/config/financial-profile | Current resolved FinancialProfileConfig — useful when debugging why a rebuild … |
Authentication
| Method | Path | Description |
|---|---|---|
GET | /.well-known/oauth-client/binance | Returns Minara's public OAuth Client ID Metadata Document for the Binance Agenti… |
POST | /v1/auth/elevenlabs/api-key | Save an ElevenLabs key for speech synthesis and transcription. Validated against… |
GET | /v1/auth/status | List all configured auth profiles (OpenAI / Anthropic / OpenRouter / Minara). |
POST | /v1/auth/oauth/openai/init | Start an OpenAI Codex device-code login flow. Returns \{ flowId, userCode, verif… |
GET | /v1/auth/oauth/openai/poll | Poll an in-flight OpenAI device-code flow by flowId (from /v1/auth/oauth/open… |
GET | /v1/auth/oauth/openai/callback | Retired in 2026-05. The previous PKCE-loopback redirect target now returns 410 G… |
POST | /v1/auth/oauth/openrouter/init | Start an OpenRouter OAuth PKCE flow. |
GET | /v1/auth/oauth/openrouter/callback | OAuth redirect target for OpenRouter. |
POST | /v1/auth/openrouter/api-key | Skip the OAuth flow and register an OpenRouter API key directly. |
POST | /v1/auth/oauth/anthropic/init | Start the Anthropic device-flow reuse path (reuses an existing Claude CLI login)… |
POST | /v1/auth/oauth/anthropic/exchange | Complete the Anthropic device flow by exchanging the verifier for credentials. |
DELETE | /v1/auth/:provider | Remove a stored auth profile. :provider is openai |
POST | /v1/auth/oauth/xai/init | Start a SuperGrok-style PKCE flow against auth.x.ai. The gateway binds the loopb… |
GET | /v1/auth/oauth/flows/:flowId | Query the in-process orchestrator for the status of an in-flight web-OAuth flow.… |
DELETE | /v1/auth/oauth/flows/:flowId | Cancel an in-flight web-OAuth flow — closes the bound loopback port immediately … |
POST | /v1/auth/openai/api-key | Save an OpenAI platform API key (api.openai.com). Validates via GET /v1/models b… |
POST | /v1/auth/anthropic/api-key | Save an Anthropic platform API key. Validates via GET /v1/models before persisti… |
POST | /v1/auth/xai/api-key | Save an xAI (Grok) API key. Validates via GET /v1/models before persisting. |
POST | /v1/auth/kimi/api-key | Save a Kimi API key. Checks the official model list first; saveAnyway allows s… |
POST | /v1/auth/ollama/api-key | Save an Ollama Cloud API key. Validates the key against the configured Ollama ho… |
GET | /v1/auth/preferred-provider | Read the user's explicit "Use this provider" override from credentials.json (llm… |
PUT | /v1/auth/preferred-provider | Set or clear the preferred provider override. Live-probes the selected credentia… |
GET | /v1/security/totp/status | Projection of /auth/me through the agent's normalizeTotpStatus adapter. tot… |
GET | /v1/user/wallet-addresses | Compatibility address-only projection of /auth/me's wallets object. Returns … |
GET | /v1/user/profile | Complete signed-in Minara account profile. Preserves the frontend /auth/me fie… |
POST | /v1/security/totp/generate | Mints a fresh TOTP secret for the user to add to an authenticator app, as an ot… |
POST | /v1/security/totp/enable | Activates TOTP after the user proves they configured the authenticator by submit… |
POST | /v1/security/totp/disable | Turns TOTP off without removing the device binding. Requires both a fresh TOTP c… |
POST | /v1/security/totp/verify | Checks a 6-digit code against the account's current secret and changes nothing. … |
POST | /v1/security/totp/unbind | Irrevocably removes the authenticator binding — re-enabling requires a fresh sca… |
POST | /v1/security/email-code | Triggers POST /auth/email/code upstream so the user can receive a fresh verifi… |
PUT | /v1/security/totp/settings | Store the account's new-device-login and withdraw TOTP preferences. The new-devi… |
POST | /v1/auth/minara/oauth/start | Kick off the Minara platform OAuth 2.0 + PKCE login. Binds a loopback callback s… |
POST | /v1/auth/minara/oauth/poll | Poll the in-flight OAuth flow by flow_id. Returns pending until the callback fir… |
POST | /v1/auth/oauth/minara/init | Alias of the Minara OAuth start under the shared provider-reauth namespace. Runs… |
DELETE | /v1/auth/minara | Forget the stored Minara token; subsequent calls become unauthenticated. |