Run a governed retirement simulation

POST

/api/v1/fire-decision/scenarios/{scenarioId}/retirement-simulation

curl --request POST \
  --url https://indepai.app/api/v1/fire-decision/scenarios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/retirement-simulation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "revisionId": "550e8400-e29b-41d4-a716-446655440000", "seed": "example", "pathCount": 1, "horizonYears": 1, "stressScenarioId": "baseline", "targetSuccessProbability": 1 }'

• Production server
• Staging server
• Development server

Runs the bounded synchronous joint nominal return/inflation/FX model for an owner-scoped immutable revision. The endpoint returns a blocked result when no approved compatible parameter set is available; it never substitutes request-supplied or legacy IID data.

Authorizations

• bearerAuth

Parameters

Path Parameters

scenarioId

required

Owner-scoped decision scenario UUID

string format: uuid

Header Parameters

Idempotency-Key

required

Client-generated replay key

string format: uuid

Request Body

Media typeapplication/json

object

revisionId

required

Unique identifier (UUID v4)

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

seed

required

string

>= 1 characters <= 128 characters /^[a-zA-Z0-9._:-]+$/

pathCount

required

integer

>= 100 <= 2000

horizonYears

required

integer

>= 1 <= 60

stressScenarioId

required

Any of:

string

string

Allowed values: baseline

string

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

targetSuccessProbability

required

number

<= 1

Responses

200

Completed or explicitly blocked planning execution

Media typeapplication/json

object

success

required

Always true for success responses

boolean

data

required

object

schemaVersion

required

string

Allowed values: planning-execution/1

scenarioId

required

Unique identifier (UUID v4)

string format: uuid

revisionId

required

Unique identifier (UUID v4)

string format: uuid

idempotencyKey

required

Unique identifier (UUID v4)

string format: uuid

requestHash

required

string

/^[a-f0-9]{64}$/

execution

required

object

mode

required

string

Allowed values: synchronous

status

required

string

Allowed values: completed blocked indeterminate cancelled timed_out

timeoutMs

required

integer

> 0 <= 10000

receipt

required

object

persisted

required

boolean

reason

required

string

Allowed values: APPROVED_PARAMETER_DATA_UNAVAILABLE RESULT_NOT_RECEIPT_GRADE EVIDENCE_RECEIPT_FOUNDATION_INCOMPLETE

kind

required

string

Allowed values: retirement_simulation

result

required

One of:

object

object

ok

required

boolean

value

required

object

readiness

required

string

Allowed values: ready limited

identity

required

object

engineVersion

required

string

Allowed values: retirement-sim/1

modelVersion

required

string

Allowed values: historical-block-regime/1

parameterSetId

required

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

seriesManifestHash

required

string

/^[a-f0-9]{64}$/

prngVersion

required

string

Allowed values: mulberry32-derived-streams/1

seed

required

string

>= 1 characters <= 128 characters

pathCount

required

integer

>= 1 <= 5000

horizonMonths

required

integer

>= 12 <= 720

contractHash

required

string

/^[a-f0-9]{64}$/

scenarioId

required

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

parameterManifest

required

object

modelVersion

required

string

Allowed values: historical-block-regime/1

parameterSetId

required

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

seriesManifestHash

required

string

/^[a-f0-9]{64}$/

sourceSeries

required

Array<object>

>= 1 items <= 256 items

object

id

required

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

kind

required

string

Allowed values: nominal_return inflation fx cash_yield

publisher

required

string

>= 1 characters <= 240 characters

version

required

string

>= 1 characters <= 120 characters

hash

required

string

/^[a-f0-9]{64}$/

license

required

string

>= 1 characters <= 240 characters

observationStart

required

string

>= 1 characters <= 32 characters

observationEnd

required

string

>= 1 characters <= 32 characters

coverageKeys

required

Array<string>

>= 1 items <= 256 items

observationPeriod

required

object

start

required

string

>= 1 characters <= 32 characters

end

required

string

>= 1 characters <= 32 characters

frequency

required

string

Allowed values: annual

blockLength

required

object

method

required

string

Allowed values: reviewer_selected autocorrelation_review

years

required

integer

> 0 <= 60

missingDataTreatment

required

string

Allowed values: complete_joint_rows_only

portfolioProjectionRule

required

string

Allowed values: native_factor_return_then_position_fee

residualTailTreatment

required

string

Allowed values: none

assetFactors

required

Array<string>

>= 1 items <= 128 items

currencies

required

Array<string>

>= 1 items <= 64 items

inflationSeries

required

Array<string>

>= 1 items <= 128 items

reportingInflationSeriesId

required

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

fxQuoteConvention

required

string

Allowed values: usd_per_currency_unit

selectedStressScenario

required

object

id

required

string

>= 1 characters <= 160 characters /^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/

description

required

string

>= 1 characters <= 500 characters

prefixObservationIndexes

required

Array<integer>

<= 2000 items

shockYears

required

integer

<= 60

returnShockByFactor

object

key

additional properties

number

inflationShockBySeries

object

key

additional properties

number

fxShockByCurrency

object

key

additional properties

number

approval

required

object

status

required

string

Allowed values: draft approved suspended

reviewer

required

string

>= 1 characters <= 160 characters

approvedAt

required

Timestamp in ISO 8601 format

string format: date-time

effectiveFrom

required

Timestamp in ISO 8601 format

string format: date-time

warningExpiresAt

required

Timestamp in ISO 8601 format

string format: date-time

hardExpiresAt

required

Timestamp in ISO 8601 format

string format: date-time

legacyComparator

required

string

Allowed values: iid-lognormal-real/legacy

successDefinition

required

string

Allowed values: all_required_net_spending_funded_through_horizon

successProbability

required

number

<= 1

fundedSpendingRatio

required

object

p10

required

number

p50

required

number

p90

required

number

depletionYear

required

object

p10

required

number

p50

required

number

p90

required

number

endBalanceRealUsd

required

object

p10

required

number

p50

required

number

p90

required

number

maxDrawdown

required

object

p10

required

number

p50

required

number

p90

required

number

taxPaidRealUsd

object

p10

required

number

p50

required

number

p90

required

number

fxContributionRealUsd

required

object

p10

required

number

p50

required

number

p90

required

number

annualBalanceRealUsd

required

Array<object>

>= 2 items <= 61 items

object

year

required

integer

<= 60

balance

required

object

p10

required

number

p50

required

number

p90

required

number

representativePaths

required

Array<object>

object

percentile

required

string

Allowed values: p10 p50 p90

pathIndex

required

integer

<= 4999

depletionYear

required

integer | null

> 0 <= 60

fundedSpendingRatio

required

number

<= 1

endBalanceRealUsd

required

number

annualBalanceRealUsd

required

Array<number>

>= 2 items <= 61 items

targetDiagnostics

required

object

targetSuccessProbability

required

number

<= 1

targetMet

required

boolean

survivalCount

required

integer

<= 5000

modeledPathCount

required

integer

> 0 <= 5000

earlyDepletionShare

required

number

<= 1

sequenceRiskWindow

required

object

startYear

required

integer

> 0 <= 60

endYear

required

integer

> 0 <= 60

warnings

required

Array<object>

<= 32 items

object

code

required

string

Allowed values: PARAMETER_SET_WARNING_EXPIRY TAX_EXCLUDED CURRENT_TAX_LAW_HELD_STATIC ANNUAL_MODEL_GRANULARITY HISTORICAL_SAMPLE_LIMITATION STRESS_SCENARIO_APPLIED

detail

required

string

>= 1 characters <= 1000 characters

object

object

ok

required

boolean

readiness

required

string

Allowed values: blocked

reasons

required

Array<string>

>= 1 items <= 32 items

Allowed values: APPROVED_PARAMETER_SET_UNAVAILABLE CLAIM_NOT_REQUESTED INVALID_INPUT PARAMETER_SET_INVALID PARAMETER_SET_NOT_APPROVED PARAMETER_SET_NOT_EFFECTIVE PARAMETER_SET_EXPIRED SERIES_MANIFEST_INCOMPLETE UNSUPPORTED_ASSET_FACTOR UNSUPPORTED_CURRENCY UNSUPPORTED_INFLATION_SERIES STRESS_SCENARIO_UNKNOWN EXECUTION_CANCELLED EXECUTION_TIMEOUT NUMERIC_RESULT_INVALID

meta

object

timestamp

required

Response timestamp

string format: date-time

version

API version

string

default: 1.0

Example

{
  "success": true,
  "data": {
    "schemaVersion": "planning-execution/1",
    "scenarioId": "550e8400-e29b-41d4-a716-446655440000",
    "revisionId": "550e8400-e29b-41d4-a716-446655440000",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "execution": {
      "mode": "synchronous",
      "status": "completed"
    },
    "receipt": {
      "persisted": false,
      "reason": "APPROVED_PARAMETER_DATA_UNAVAILABLE"
    },
    "kind": "retirement_simulation",
    "result": {
      "ok": true,
      "value": {
        "readiness": "ready",
        "identity": {
          "engineVersion": "retirement-sim/1",
          "modelVersion": "historical-block-regime/1",
          "prngVersion": "mulberry32-derived-streams/1"
        },
        "parameterManifest": {
          "modelVersion": "historical-block-regime/1",
          "sourceSeries": [
            {
              "kind": "nominal_return"
            }
          ],
          "observationPeriod": {
            "frequency": "annual"
          },
          "blockLength": {
            "method": "reviewer_selected"
          },
          "missingDataTreatment": "complete_joint_rows_only",
          "portfolioProjectionRule": "native_factor_return_then_position_fee",
          "residualTailTreatment": "none",
          "fxQuoteConvention": "usd_per_currency_unit",
          "approval": {
            "status": "draft",
            "approvedAt": "2024-01-15T10:30:00Z",
            "effectiveFrom": "2024-01-15T10:30:00Z",
            "warningExpiresAt": "2024-01-15T10:30:00Z",
            "hardExpiresAt": "2024-01-15T10:30:00Z"
          },
          "legacyComparator": "iid-lognormal-real/legacy"
        },
        "successDefinition": "all_required_net_spending_funded_through_horizon",
        "representativePaths": [
          {
            "percentile": "p10"
          }
        ],
        "warnings": [
          {
            "code": "PARAMETER_SET_WARNING_EXPIRY"
          }
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

400

Invalid planning contract

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

401

Authentication required

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

404

Owned scenario revision not found

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

409

Idempotency key conflict

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

413

Request body exceeds 64 KiB

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

415

Content type must be application/json

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}

429

Rate limit exceeded

Media typeapplication/json

object

success

required

Always false for error responses

boolean

error

required

Error type

string

code

Machine-readable error code

string

details

Detailed validation errors

Array<object>

object

path

required

Path to the invalid field

string

message

required

Error message

string

Example

{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}