Skip to main content
POST
Get a portfolio snapshot with your prices

Authorizations

​
x-api-key
string
header
required

Raw API key shown once when created in the Allocait app (Settings > API keys). Send it verbatim in this header; the server stores and compares only its SHA-256 hash. Allocait generates every key: alc_ followed by 64 lowercase hex characters. Keys issued before 2026-10-10 are 64 hex characters with no prefix and keep working. A key may carry an expiry (90 days or 1 year, or never). A malformed, unknown, revoked or expired key gets 401 with no further detail, and a malformed one is refused before any lookup. Keys cannot be created through this API.

Query Parameters

​
include_rebalance
boolean

Add the rebalance block. Default false. Any other value than true or false is a 400.

Body

application/json
​
portfolio_id
string<uuid>
required
​
scenario_id
string<uuid> | null
​
prices
object

Symbol-to-price map. Keys are ticker symbols, matched case-insensitively (normalised to uppercase); values are numbers, 0 or more. 0 is a real price, for example an option that expired worthless. On the agent surface, a symbol you leave out of this map is never priced from Allocait's own data (ADR-036); it comes back null, or the call is refused, depending on the endpoint. Two exceptions are the user's own numbers, not Allocait's: a held option with a mark is priced at its mark, so you may leave it out, and a price you pass for it replaces the mark for that call only and is never stored; an option past its expiry counts 0 whatever you pass (ADR-147).

Example:

Response

Portfolio snapshot, priced as far as prices reaches

Single denormalized blob: portfolio + positions + rules + compliance violations + condition monitors, and rebalance amounts when the request sets include_rebalance=true. The agent's primary "look at the world" response. See ADR-007 and ADR-026. A check answer comes from compliance; sized amounts are there only when asked for (ADR-113). prices_complete / unpriced_symbols (the fields ComplianceResponse / RebalanceResponse both omit for the same reason) are not carried on this surface either: both are computed from Allocait's own stored quote, not from your coverage of it, so neither can be scrubbed the way current_price, total_value and exposure are; use symbols_to_price instead (ADR-036).

​
portfolio
object

The portfolio header as carried inside PortfolioSnapshot.portfolio. PortfolioSummary without position_count; the RPC builds this object itself and does not count positions here.

​
scenario_id
string<uuid> | null
​
total_value
number | null

Null when any non-cash position is unpriced; a value spanning the whole portfolio can't stand on one stored quote (ADR-036). Present only once every non-cash position is covered by your prices map or owns its price (an option with a mark, or an expired one, ADR-147). Signed, since shorts subtract, so it can be zero or negative. At zero or less every position_pct is null and compliance reads unjudged (ADR-153).

​
exposure
object | null

How much of the portfolio gains if prices rise, as percents of its value: long, short, net and gross, by asset class and per holding. A reading, not a rule; there is no range, cap or status to compare it with. Always present. Null unless your prices map holds a number for every non-cash holding, and while any holding is unpriced, even where Allocait holds a quote of its own that could fill the gap: every percent is a share of the whole book, so one stored quote would reach all of them (ADR-036, ADR-142). A holding that owns its price, an option with a mark or an expired one, counts as covered. Options count at their premium (ADR-147). Computed from your prices and the user's marks, and never stored.

Example:
​
price_source
enum<string>

overrides once every symbol this response needed came from your prices map (symbols_to_price is then empty); unpriced while at least one still does not. Allocait's own stored quote (market_data) never appears on this surface (ADR-036).

Available options:
overrides,
unpriced
​
symbols_to_price
string[]

Every symbol, sorted, that you would need to add to prices to clear every null from this response. Empty once the payload is entirely your own numbers.

​
positions
object[]
​
expired_options
integer

How many held options have passed their expiry (expired_on set, shares not 0). The user's own record, so it needs no price and is present whatever else is null. Allocait changes nothing on them and sends no alert; the person decides what each became (ADR-147).

​
rules
object[]

The active scenario's position rules. Same fields as GET /position-rules minus the ids and timestamps.

​
compliance
object

Null when any non-cash position is unpriced. An {error} object when the portfolio has no scenario to evaluate against. Otherwise the shape POST /compliance/check returns, computed from this request's prices, including status, issue_count and unchecked.

​
rebalance
object

Present only when the request sets include_rebalance=true (ADR-113); left out otherwise. Same nullability as compliance: null when any non-cash position is unpriced, an {error} object when no scenario is set, otherwise the same shape POST /rebalance/preview returns, computed from this request's prices.

​
monitors
object[]

Each condition monitor measured against the levels and ranges the user recorded, at the price you passed for its symbol (null, unmeasured, if you did not). One entry per (monitor, resolved symbol); [] when the portfolio has no monitors. See ADR-020 and ADR-026.

​
playbooks_needing_input
object[]

The portfolio's playbooks with at least one blank cell today (US Eastern, or the playbook's pinned date), as the playbook's needs_input counts them: blank cells of Inputs that are not optional. [] when none. The user's own recorded data, never priced (ADR-204).

​
generated_at
string<date-time>