Create Portfolio Block

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

Create a portfolio with optional initial positions in a single atomic envelope. Each position references an existing security; this operation never mints securities (use create-security). Whole envelope validates before any write.

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

portfoliorequired

PortfolioBlockPortfolioFields

Core portfolio fields — name, currency, owning entity, etc.

PortfolioBlockPortfolioFields fields

Field	Type	Description
`name`required	string	Display name for the portfolio. 1-200 characters.
`description`optional	string	Free-text description of the portfolio.
`strategy`optional	string	Free-text strategy classification (e.g. `value`, `growth`, `income`). Open vocabulary.
`inception_date`optional	string (date)	Date the portfolio was established (YYYY-MM-DD).
`base_currency`optional	string	ISO 4217 currency code used for portfolio-level aggregates (e.g. `total_cost_basis_dollars`). Default: `USD`
`entity_id`optional	string	ID of the owning entity (e.g. fund, trust, or person). Optional — leave unset for unattributed portfolios.

positionsoptional

PortfolioBlockPositionAdd[]

Initial positions to mint inside the new portfolio. Each references an existing security; pass `[]` to create an empty portfolio.

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.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboinvestor/{graph_id}/operations/create-portfolio-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "portfolio": {
    "base_currency": "USD",
    "description": "Mid-cap public equities",
    "entity_id": "ent_acme_holdings",
    "inception_date": "2026-01-01",
    "name": "Q1 2026 Growth",
    "strategy": "growth"
  },
  "positions": [
    {
      "acquisition_date": "2026-01-15",
      "cost_basis": 1850000,
      "currency": "USD",
      "current_value": 2010000,
      "quantity": 100,
      "quantity_type": "shares",
      "security_id": "sec_aapl",
      "valuation_date": "2026-04-30",
      "valuation_source": "broker_statement"
    },
    {
      "acquisition_date": "2026-02-08",
      "cost_basis": 2125000,
      "currency": "USD",
      "current_value": 2240000,
      "quantity": 50,
      "quantity_type": "shares",
      "security_id": "sec_msft",
      "valuation_date": "2026-04-30",
      "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