RoboInvestor

Create Security

Register a security (common stock, preferred stock, warrant, convertible note, etc.) owned by this graph's entity. Optionally cross-links to an issuing entity in another graph via source_graph_id for mutual-handshake attribution.

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.

post/extensions/roboinvestor/{graph_id}/operations/create-security

Request

  • Base URL: https://api.robosystems.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.robosystems.ai/extensions/roboinvestor/{graph_id}/operations/create-security
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

entity_idstring nullable

ID of the issuing entity. Optional only if source_graph_id is set (pre-association before the entity is finalized).

source_graph_idstring nullable

Optional pre-association to a tenant company graph. Lets you mint securities for an entity that hasn't been promoted to a real entity_id yet.

namestring required

Display name for the security (e.g. Common Stock Class A, Series A Preferred). 1-200 characters.

security_typestring required

Instrument family. Open vocabulary — common values: common_stock, preferred_stock, warrant, convertible_note, safe, option, llc_unit, lp_interest, restricted_stock_unit.

security_subtypestring nullable

Free-text refinement of security_type (e.g. class_a, series_a, series_seed). No vocabulary enforcement.

termsobject

Instrument-specific terms blob (JSONB). Shape depends on security_type — common keys include liquidation_preference, strike_price_cents, discount_pct, valuation_cap_cents, maturity_date, vesting. Used by future waterfall-distribution modeling; treat as authoritative storage for instrument mechanics.

authorized_sharesinteger nullable

Total shares the issuer is authorized to issue for this class. null for instruments where shares aren't a meaningful unit (e.g. convertible notes pre-conversion).

outstanding_sharesinteger nullable

Shares currently issued and outstanding. Should be ≤ authorized_shares when both are set.

Example request

{
  "authorized_shares": 10000000,
  "entity_id": "ent_acme_holdings",
  "name": "Common Stock Class A",
  "outstanding_shares": 6500000,
  "security_subtype": "class_a",
  "security_type": "common_stock"
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

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

Changes

No recorded changes to this operation across all 1 revision of this API.