Book a demo

create_portfolio

Create a portfolio

act entity tenant-private since 2026-10-01

Creates an empty portfolio, a named set of orgs, in an account or, for staff, in no account. An account owner creates only into an account they own. Send an Idempotency-Key header: a retry with the same key and inputs returns the same portfolio and creates nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first
idempotency
keyed
emits
portfolio.created
MCP tool
create_portfolio
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/create_portfolio

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
nametextrequired1 to 200 characters
The portfolio's name.
account_idaccount_idoptionaltradehq-account-id
The owning account. Required of an account owner, and one they own; staff may leave it out.

Response

  • portfolio_id · string · The new portfolio's id.
  • name · string · Its name.
  • account_id · stringnull · Its account; null for a staff portfolio.
  • created_by · string · Who created it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "portfolio_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-portfolio-id",
      "description": "The new portfolio's id.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "Its name.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "Its account; null for a staff portfolio.",
      "x-data-class": "operational"
    },
    "created_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who created it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "portfolio_id",
    "name",
    "account_id",
    "created_by"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates a portfolio
  • Outbound: crosses to no counterparty

Events

Related

None.