Update Portfolio Block

post/extensions/roboinvestor/{graph_id}/operations/update-portfolio-block

Patch portfolio fields and apply position deltas (add / update / dispose) atomically. Partial failures roll back.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field Type Description

portfolio_idrequired

string

Target portfolio ID.

portfoliooptional

PortfolioBlockPortfolioPatch

Patch to portfolio core fields. Omit or leave fields unset to leave the portfolio core unchanged.

PortfolioBlockPortfolioPatch fields

Field	Type	Description
`name`optional	string	New display name. Unset = unchanged.
`description`optional	string	New description. Unset = unchanged.
`strategy`optional	string	New strategy classification. Unset = unchanged.
`inception_date`optional	string (date)	New inception date (YYYY-MM-DD). Unset = unchanged.
`base_currency`optional	string	New ISO 4217 base currency code. Unset = unchanged. Note: changing base currency does not retroactively reprice historical positions.
`entity_id`optional	string	New owning-entity ID. Unset = unchanged.

positionsoptional

PortfolioBlockPositions

Position deltas — additions, in-place updates, and dispositions — applied atomically with the portfolio patch.

PortfolioBlockPositions fields

Field Type Description

addoptional

PortfolioBlockPositionAdd[]

New positions to mint inside this portfolio. Each references an existing `security_id`.

PortfolioBlockPositionAdd fields

Field	Type	Description
`security_id`required	string	ID of the existing security this position holds. Securities are minted via `create-security`; the operation returns 404 if the ID is unknown.
`quantity`required	number	Quantity held, in units defined by `quantity_type` (e.g. share count for `shares`, face value for `principal`).
`quantity_type`optional	string	Unit basis for `quantity`. Common values: `shares` (equity units), `units` (generic), `principal` (debt face value). Default: `shares`
`cost_basis`optional	integer	Total cost basis for this lot, in cents of `currency`. Stored as integer cents to avoid float precision drift; $1,250.00 USD is `125000`. Default: `0`
`currency`optional	string	ISO 4217 currency code for `cost_basis` and `current_value`. Default: `USD`
`current_value`optional	integer	Latest mark-to-market value in cents of `currency`, or `null` if unmarked. Pair with `valuation_date` and `valuation_source` when set.
`valuation_date`optional	string (date)	Date `current_value` was sourced (YYYY-MM-DD).
`valuation_source`optional	string	Free-text source attribution for `current_value` (e.g. `manual`, `broker_statement`, vendor name).
`acquisition_date`optional	string (date)	Date the position was originally acquired (YYYY-MM-DD).
`notes`optional	string	Free-text notes attached to the position.

updateoptional

PortfolioBlockPositionUpdate[]

Patches to existing positions, addressed by position `id`. Unset fields on each entry are left unchanged.

PortfolioBlockPositionUpdate fields

Field	Type	Description
`id`required	string	Target position ID. Must belong to the portfolio identified by `portfolio_id` on the parent operation.
`quantity`optional	number	New quantity in units of `quantity_type`. Unset = unchanged.
`quantity_type`optional	string	New unit basis (`shares` \| `units` \| `principal`). Unset = unchanged.
`cost_basis`optional	integer	New cost basis in cents of the position's currency. Unset = unchanged.
`current_value`optional	integer	New mark-to-market value in cents. Unset = unchanged. Set alongside `valuation_date` / `valuation_source` to record a fresh valuation event.
`valuation_date`optional	string (date)	New valuation date (YYYY-MM-DD). Unset = unchanged.
`valuation_source`optional	string	New valuation source attribution. Unset = unchanged.
`acquisition_date`optional	string (date)	New acquisition date (YYYY-MM-DD). Unset = unchanged.
`notes`optional	string	New notes. Unset = unchanged.

disposeoptional

PortfolioBlockPositionDispose[]

Positions to soft-dispose, addressed by position `id`. Status flips to `disposed` and `disposition_date` is stamped.

PortfolioBlockPositionDispose fields

Field	Type	Description
`id`required	string	Target position ID to dispose. Must belong to the portfolio identified by `portfolio_id` on the parent operation.
`disposition_reason`optional	string	Optional free-text reason recorded under `metadata.disposition_reason` on the disposed position.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboinvestor/{graph_id}/operations/update-portfolio-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "portfolio": {
    "description": "Pivoted toward defensive holdings"
  },
  "portfolio_id": "port_q1_growth_2026",
  "positions": {
    "add": [],
    "dispose": [
      {
        "disposition_reason": "Liquidated; rotated capital",
        "id": "pos_oldcorp_lot_3"
      }
    ],
    "update": [
      {
        "current_value": 1980000,
        "id": "pos_aapl_lot_1",
        "valuation_date": "2026-05-06",
        "valuation_source": "broker_statement"
      },
      {
        "current_value": 2310000,
        "id": "pos_msft_lot_1",
        "valuation_date": "2026-05-06",
        "valuation_source": "broker_statement"
      }
    ]
  }
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

PortfolioBlockEnvelope

Command-specific result payload

PortfolioBlockEnvelope fields

Field Type Description

idrequired

string

Portfolio ID (`port_*` ULID).

namerequired

string

Display name.

descriptionoptional

string

Free-text description.

strategyoptional

string

Free-text strategy classification.

inception_dateoptional

string (date)

Date the portfolio was established.

base_currencyrequired

string

ISO 4217 currency code for portfolio aggregates.

owneroptional

EntityLite

Embedded owning entity, when set. `null` for unattributed portfolios.

EntityLite fields

Field	Type	Description
`id`required	string	Entity ID (`ent_*` ULID).
`name`required	string	Display name of the entity.
`source_graph_id`optional	string	Tenant graph this entity is anchored to, when known. `null` for entities not yet linked to a graph.

positionsrequired

PositionBlock[]

All positions in this portfolio, including disposed ones (filter by `status` for active-only display).

PositionBlock fields

Field	Type	Description
`id`required	string	Position ID (`pos_*` ULID).
`quantity`required	number	Quantity held in `quantity_type` units.
`quantity_type`required	string	Unit basis (`shares`, `units`, `principal`).
`cost_basis_dollars`required	number	Cost basis in dollars (pre-converted from cents).
`current_value_dollars`optional	number	Latest mark-to-market value in dollars. `null` when the position has not been marked.
`valuation_date`optional	string (date)	Date the current value was sourced.
`valuation_source`optional	string	Free-text source attribution for the valuation.
`acquisition_date`optional	string (date)	Date the position was acquired.
`status`required	string	Lifecycle state (`active`, `disposed`, `archived`). See `PositionResponse.status` for the full vocabulary.
`notes`optional	string	Free-text notes attached to the position.
`security`required	SecurityLite	Embedded security details — name, type, issuer.

total_cost_basis_dollarsrequired

number

Sum of `cost_basis_dollars` across every position.

total_current_value_dollarsoptional

number

Sum of `current_value_dollars` across every position. `null` when any active position lacks a mark.

active_position_countrequired

integer

Count of positions with `status='active'`.

created_atrequired

string (date-time)

Row creation timestamp (UTC).

updated_atrequired

string (date-time)

Last-modified timestamp (UTC).

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error