ATLAS · Portfolios

ATLAS base URL: https://atlas-api.trinitytrade.io

This page documents public GET routes: /health and portfolio endpoints under /api/v1/portfolios/ (list, summary, detail, alerts, performance). Use the sections below for paths, parameters, example curls, and sample responses.

Paths in this guide. Examples use public routes under /api/v1/portfolios/demo/; the JSON you see here matches the portfolio resources you access in production on the routes and base URL issued with your credentials. Contact us for API onboarding.

Authentication

Authorization: Bearer <access_token>. Partners receive short-lived access tokens (OAuth 2.0–style client credentials) scoped to their integration; send the header on every portfolio request. Missing, expired, or invalid tokens return 401.

GET

Health

/health

Liveness probe for load balancers and monitoring.

Auth: None.

Responses

Status	Description
`200`	JSON: status

Example

export ATLAS_API="${ATLAS_API:-https://atlas-api.trinitytrade.io}"
curl -sS "$ATLAS_API/health"

Response

GET

List User Portfolios

/api/v1/portfolios/demo/list

Returns every portfolio as an array of portfolio rows (ids, capital, position counts, metadata).

Auth: See Authentication — portfolio data.

Responses

Status	Description
`200`	PortfolioResponse[]
`500`	Service error

Example

export ATLAS_API="${ATLAS_API:-https://atlas-api.trinitytrade.io}"
curl -sS "$ATLAS_API/api/v1/portfolios/demo/list"

Response

GET

List User Portfolio Summaries

/api/v1/portfolios/demo/list/summary

One summary row per portfolio, including top holdings, movers, and roll-up metrics.

Auth: See Authentication — portfolio data.

Responses

Status	Description
`200`	PortfolioSummaryResponse[]
`500`	Service error

Example

export ATLAS_API="${ATLAS_API:-https://atlas-api.trinitytrade.io}"
curl -sS "$ATLAS_API/api/v1/portfolios/demo/list/summary"

Response

GET

Get Portfolio Details

/api/v1/portfolios/{portfolio_id}

Full portfolio document for the id in the path—allocations, risk settings, totals. Unknown ids return 404.

Auth: See Authentication — portfolio data.

Parameters

Name	In	Type	Required	Description
`portfolio_id`	path	string	Yes	Portfolio id

Responses

Status	Description
`200`	DetailedPortfolioResponse
`404`	Not found

Example

export ATLAS_API="${ATLAS_API:-https://atlas-api.trinitytrade.io}"
curl -sS "$ATLAS_API/api/v1/portfolios/demo/c293a410-0ffd-4c43-9599-f0e253d03d4c"
# Swap id: copy portfolio_id from GET .../list if this example id is stale.

Response

GET

Get Portfolio Alerts

/api/v1/portfolios/{portfolio_id}/alerts

Aggregated alerts for open positions in the given portfolio (priorities, thresholds, messages).

Auth: See Authentication — portfolio data.

Parameters

Name	In	Type	Required	Description
`portfolio_id`	path	string	Yes	Portfolio id

Responses

Status	Description
`200`	PortfolioAlertsResponse
`404`	Not found

Example

export ATLAS_API="${ATLAS_API:-https://atlas-api.trinitytrade.io}"
curl -sS "$ATLAS_API/api/v1/portfolios/demo/31f3b668-d39d-4582-8f0c-ab5af77ac5c1/alerts"

Response

GET

Get Portfolio Performance

/api/v1/portfolios/{portfolio_id}/performance

Daily time series of total portfolio value. See PortfolioPerformanceResponse below for how to read success, data, and metadata. Optional start_date and end_date (YYYY-MM-DD) may be accepted; when the server returns a precomputed series, filter client-side if you need a shorter window.

Auth: See Authentication — portfolio data.

Parameters

Name	In	Type	Required	Description
`portfolio_id`	path	string	Yes	Portfolio id
`start_date`	query	string	No	YYYY-MM-DD
`end_date`	query	string	No	YYYY-MM-DD

Responses

Status	Description
`200`	success, data[], metadata
`404`	Unknown portfolio or no performance available
`500`	Server error

Example

export ATLAS_API="${ATLAS_API:-https://atlas-api.trinitytrade.io}"
curl -sS "$ATLAS_API/api/v1/portfolios/demo/31f3b668-d39d-4582-8f0c-ab5af77ac5c1/performance"
# Optional window: append ?start_date=2024-01-01&end_date=2024-12-31

Response

PortfolioResponsePublic

One element of the JSON array from GET /api/v1/portfolios/demo/list. Atlas validates with List[PortfolioResponsePublic]; user_uid is excluded from public JSON (the sample response on this page may still show legacy mock fields).

Show full field reference (table)

Field	Type	Description
`portfolio_id`	string	Unique portfolio identifier.
`name`	string	Portfolio name.
`description`	string or null	Optional description.
`total_capital`	number	Total available capital.
`allocated_capital`	number	Capital allocated to open positions.
`remaining_capital`	number	Unallocated cash.
`position_count`	integer	Number of positions.
`created_at`	string (datetime)	Creation timestamp.
`currency`	string	Currency code (e.g. USD).
`trace_id`	string	Request correlation id for logs.

PortfolioSummaryResponsePublic

One element of the JSON array from GET /api/v1/portfolios/demo/list/summary (proxied through IRIS in the try-it panel). user_uid is omitted from public JSON. Nested top_holdings and top_movers rows follow PositionSummaryForList.

Show full field reference (tables)

Summary object

Field	Type	Description
`portfolio_id`	string	Unique portfolio identifier.
`name`	string	Portfolio name.
`description`	string or null	Optional description.
`total_capital`	number	Total capital.
`allocated_capital`	number	Allocated capital.
`remaining_capital`	number	Remaining cash.
`position_count`	integer	Position count.
`created_at`	string (datetime)	Created at.
`updated_at`	string or null	Last Firestore update.
`currency`	string	Currency code.
`top_holdings`	array	Top positions by value (`PositionSummaryForList`).
`top_movers`	array	Top open positions by absolute daily % move.
`total_current_value`	number	Aggregate current market value.
`total_unrealized_pnl`	number	Unrealized P&L on open positions.
`total_realized_pnl`	number	Realized P&L on closed positions.
`days_change`	number	Portfolio value change vs prior day.
`alerts_count`	integer	Active alerts for this portfolio.
`urgent_alerts` / `high_alerts` / `medium_alerts`	integer	Counts by priority band.
`trade_picks_count`	integer	Positions with BUY signals.
`unrealized_gains_count` / `unrealized_loss_count`	integer	Open winners / losers.
`total_return_percent`	number or null	Total return % since inception when benchmark data is available.
`spy_return_percent`	number or null	SPY return over the same window.
`spy_outperformance`	number or null	Portfolio return minus SPY (percentage points).

PositionSummaryForList

Field	Type	Description
`symbol`	string	Ticker.
`company_name`	string or null	Issuer name when known.
`shares`	number	Share quantity.
`position_value`	number	Position market value.
`stage`	string or null	Weinstein-style stage label.
`signal`	string or null	BUY / SELL / HOLD style signal.
`stage_strength`	string or null	Strength of the stage.
`percent_of_account`	number or null	Fraction of account in this name.
`current_price`	number or null	Latest price used in the summary.
`unrealized_gain`	number or null	Unrealized dollar P&L.
`unrealized_gain_percent`	number or null	Unrealized P&L vs cost.
`days_change`	number or null	Dollar change per share vs prior close.
`days_change_percent`	number or null	Percent change vs prior close.

DetailedPortfolioResponse

Body of GET /api/v1/portfolios/demo/{portfolio_id} for authenticated-style detail. Public demo responses use DetailedPortfolioResponseAnonymousDemo: user_uid, risk_quiz_answers, suggested_preset, days_change, clio_*, and settings are omitted; allocations and top_movers are truncated (e.g. two allocation rows); each allocation uses PositionDetailAnonymousDemo (signal / volatility-heavy fields omitted from JSON).

Show full field reference (tables)

Top-level portfolio

Field	Type	Description
`portfolio_id`	string	Unique portfolio identifier.
`name`	string	Portfolio name.
`description`	string or null	Optional description.
`total_capital`	number	Total capital.
`allocated_capital`	number	Allocated capital.
`remaining_capital`	number	Remaining cash.
`position_count`	integer	Total positions.
`created_at`	string (datetime)	Created at.
`updated_at`	string or null	Last update.
`currency`	string	Currency code.
`trace_id`	string	Correlation id.
`risk_settings`	object or null	Risk caps, allocation strategy, etc.
`allocations`	array	`PositionDetail` rows (demo: `PositionDetailAnonymousDemo` subset).
`open_position_count` / `closed_position_count`	integer	Open vs closed counts.
`total_current_value`	number or null	Total portfolio value.
`total_days`	integer or null	Age of portfolio in days.
`start_date`	string or null	Start date `YYYY-MM-DD`.
`total_return_percent`	number or null	Snapshot total return %.
`spy_return_percent`	number or null	SPY benchmark return %.
`spy_outperformance`	number or null	Outperformance vs SPY (points).
`total_unrealized_pnl`	number or null	Aggregate unrealized P&L.
`total_realized_pnl`	number or null	Aggregate realized P&L.
`top_movers`	array	`PositionSummaryForList` — largest daily movers.

Authenticated detail may also include user_uid, risk_quiz_answers, suggested_preset, settings, days_change, clio_config_hash, clio_run_id, and full PositionDetail objects with Athena / volatility fields.

PositionDetail (demo allocation keys)

Demo JSON keeps the trading snapshot without signal objects / ATR / BB width / volatility stop trees. Typical keys include symbol, company_name, sector, industry, shares, entry_price, position_type, position_value, target_price, stage, stage_strength, percent_of_account, historical_volatility, support_levels, resistance_levels, stop_loss, risk_amount, current_price, unrealized_gain, is_open, allocation_percentage, and related price metadata. See PositionDetail / PositionDetailAnonymousDemo in Atlas for the authoritative list.

PortfolioAlertsResponse

Body of GET /api/v1/portfolios/demo/{portfolio_id}/alerts ( response_model=PortfolioAlertsResponse).

Show full field reference (tables)

Root object

Field	Type	Description
`portfolio_id`	string	Portfolio id.
`total_alerts`	integer	Count of alerts returned.
`urgent_alerts` / `high_alerts` / `medium_alerts` / `low_alerts`	integer	Counts by priority.
`alerts`	array	List of `PositionAlert` objects.
`alert_summary`	object	Map of alert type → count.
`generated_at`	string (datetime)	When the payload was built.

PositionAlert

Field	Type	Description
`symbol`	string	Ticker.
`alert_type`	string	Enum string (e.g. `stop_loss_triggered`, `approaching_price_target`).
`priority`	string	`urgent`, `high`, `medium`, or `low`.
`message`	string	Human-readable explanation.
`shares`	number	Position size.
`entry_price`	number	Cost basis reference.
`current_price`	number or null	Mark price.
`target_price`	number or null	Target level when applicable.
`stop_loss`	number or null	Stop price.
`signal`	string or null	Trading signal snapshot.
`signal_confidence`	number or null	Confidence score.
`signal_reason`	string or null	Rationale text.
`unrealized_gain`	number or null	Unrealized P&L.
`distance_to_target`	number or null	Percent distance to target.
`distance_to_stop_loss`	number or null	Percent distance to stop.
`created_at`	string (datetime)	Alert timestamp.

PortfolioPerformanceResponse

Successful GET /api/v1/portfolios/demo/{portfolio_id}/performance returns a JSON object (cached Firestore performance doc or an on-demand calculation). Authenticated portfolio routes use the same envelope; missing cache surfaces 404 instead of an empty series.

Show performance field reference (prose + lists)

A successful response is a JSON object with three top-level fields you should rely on in integrations:

success — boolean. When true, the payload is usable.
data — array of daily points in chronological order (one entry per calendar day in the series). Each point is an object with short keys to keep payloads small:
- d — the calendar date as an integer in YYYYMMDD form (e.g. 20260407 means 2026-04-07). To convert for chart labels: year = Math.floor(d / 10000), month = Math.floor((d % 10000) / 100), day = d % 100 (zero-pad month and day if needed).
- v — total portfolio value on that date in the portfolio currency (USD in the demo examples), rounded to two decimal places. It represents the combined notion of cash plus valued positions for that day as modeled by the API; use it as the y-axis for a performance chart.
metadata — summary aligned with the series:
- start_date / end_date — inclusive span of the series (ISO YYYY-MM-DD strings).
- initial_value — baseline capital used with total_return_percent.
- current_value — should match the v on the last day in data.
- total_return_percent — overall return for the window vs initial_value.
- total_days — calendar length of the window (useful for age or labeling). Additional metadata keys may appear from time to time; treat unknown keys as optional.

Building charts and metrics. Plot d (decoded to dates) on the x-axis and v on the y-axis. You can derive day-over-day change from consecutive v values, or cumulative return vs the baseline with ((v / initial_value) - 1) * 100 using initial_value from metadata. Non-trading days may repeat the last mark; that is expected for a daily series.

Authenticated portfolio routes use the same response shape; if performance is not ready yet, the API returns 404 instead of an empty series.