Skip to main content
POST
Record one holding's new total shares

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.

Path Parameters

symbol
string
required
Example:

"ALFA"

Query Parameters

portfolio_id
string<uuid>
required

Body

application/json
shares
number
required

New TOTAL share count (0 to close without deleting). Negative is a short, recorded only on a portfolio with allow_shorts on and never in the Options class (ADR-153). For a holding filed under the Options system asset class, recorded as contracts × 100 at the per-share premium (ADR-056).

price
number

Price per share used to compute the cash difference. Required when the share count changes.

Required range: x >= 0
asset_class
string

Class name, rules text alias or id to file the holding under. A new holding without one is left unclassified.

moves
enum<integer>

Times its index the fund moves; negative is inverse. Left out, the stored value stays (1 for a new holding). Not for cash or an Options-class holding (ADR-142). A moves-only change needs no price.

Available options:
1,
2,
3,
-1,
-2,
-3
mark
number

An option's per-share premium. Only for a holding in the Options class (INVALID_INPUT otherwise). Left out, a change of the share count sets it to price, and otherwise the stored mark stays. A mark-only change needs no price and moves no cash (ADR-147).

Required range: 0 <= x <= 1000000000
sizing
enum<string>

The holding's sizing mode, as set in the app's position wizard.

Available options:
MANUAL,
MINIMUM,
BALANCED,
MAXIMUM
comment
string

Why, recorded on the action.

Response

The holding was recorded

success
boolean
portfolio_id
string<uuid>
created
object[]
updated
object[]

Share changes, plus class, sizing and Moves changes on an unchanged share count as {symbol, shares, asset_class_id, sizing}.

closed
object[]

Holdings taken to 0 shares. Closing a short is a cover, which debits cash; read the sign of the change in shares, not the word, to tell which way cash moved.

unchanged
object[]

Symbols already matching the desired state, shares and class. No RPC call was made for these.

action_ids
string<uuid>[]

The actions this call recorded, for PATCH /actions/{id} to add a comment later.

unclassified
string[]

Holdings left with no asset class. No band judges them until they have one.