Skip to main content
POST
Create a portfolio with an initial cash position

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.

Body

application/json
name
string
required
Maximum string length: 100
description
string | null
base_currency
enum<string>

Optional. If sent, it must be USD; any other value is INVALID_INPUT.

Available options:
USD
initial_cash
number

Defaults to 0.

active_scenario_id
string<uuid>

Must belong to the caller.

allow_shorts
boolean

Let holdings go short (a negative shares). Defaults to false. Ask the person before you send true.

Response

The portfolio was created

success
boolean
portfolio_id
string<uuid>
cash_position_id
string<uuid>
cash_asset_class_id
string<uuid> | null
portfolio
object

The full portfolio record, as returned by create/rename (a superset of PortfolioSummary's fields).

allow_shorts
boolean

Present only when the request sent allow_shorts: true. true when Allow shorts is on for the new portfolio, false when turning it on failed (see allow_shorts_error). A new portfolio otherwise has it off.

allow_shorts_error
object

Present only when the request sent allow_shorts: true and turning it on failed. The portfolio exists, with Allow shorts off. Turn it on with PATCH /portfolios/{id}.