---
title: "Update Security"
method: POST
path: "/extensions/roboinvestor/{graph_id}/operations/update-security"
tags: ["RoboInvestor"]
---

# Update Security

`POST /extensions/roboinvestor/{graph_id}/operations/update-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/update-security`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Update mutable fields on a security (name, type, subtype, terms, share counts, entity linkage). Unset fields are ignored.

**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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- UpdateSecurityOperation: CQRS body for `POST /operations/update-security`.
  - `entity_id` string, nullable: Reassign to a different issuing entity. Unset = unchanged.
  - `source_graph_id` string, nullable: Update the pre-association tenant graph. Unset = unchanged.
  - `name` string, nullable: New display name. Unset = unchanged.
  - `security_type` string, nullable: New instrument family. Unset = unchanged. Reclassifying a security may invalidate existing `terms` shape; the operation does not validate the cross-field consistency.
  - `security_subtype` string, nullable: New subtype refinement. Unset = unchanged.
  - `terms` object, nullable: Replacement terms blob. Pass `null`/omit to leave existing terms unchanged; pass `{}` to clear them.
  - `is_active` boolean, nullable: Active flag. Set `false` to soft-deactivate (positions remain addressable but the security is hidden from active lookups).
  - `authorized_shares` integer, nullable: New authorized share count. Unset = unchanged.
  - `outstanding_shares` integer, nullable: New outstanding share count. Unset = unchanged.
  - `security_id` string, required: Target security ID.

## Response `200`

Successful Response

- OperationEnvelopeSecurityResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` SecurityResponse: Read projection for a single security.
    - `id` string, required: Security ID (`sec_*` ULID).
    - `entity_id` string, nullable: ID of the issuing entity, when set.
    - `entity_name` string, nullable: Cached display name of the issuing entity, denormalized for list rendering. May lag the entity row's current name briefly.
    - `source_graph_id` string, nullable: Tenant graph this security is pre-associated to, when the issuer entity hasn't been promoted yet.
    - `name` string, required: Display name of the security.
    - `security_type` string, required: Instrument family (e.g. `common_stock`, `preferred_stock`, `warrant`, `convertible_note`).
    - `security_subtype` string, nullable: Optional subtype refinement (e.g. `class_a`, `series_a`).
    - `terms` object, required: Instrument-specific terms blob. Shape depends on `security_type` — see `CreateSecurityRequest.terms` for common keys.
    - `is_active` boolean, required: `true` when the security is in active status; `false` after a soft-delete or deactivation.
    - `authorized_shares` integer, nullable: Total shares authorized for this class, when set.
    - `outstanding_shares` integer, nullable: Shares currently issued and outstanding.
    - `created_at` string, date-time, required: Row creation timestamp (UTC).
    - `updated_at` string, date-time, required: Last-modified timestamp (UTC).
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)