Evaluate destination rank stability

POST

/api/v1/fire-decision/scenarios/{scenarioId}/rank-stability

curl --request POST \
  --url https://indepai.app/api/v1/fire-decision/scenarios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/rank-stability \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "revisionId": "550e8400-e29b-41d4-a716-446655440000", "destinationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "perturbations": [ { "id": "example", "label": "example", "dimension": "nominal_return", "delta": 1 } ] }'

• Production server
• Staging server
• Development server

Runs a bounded Product-approved perturbation grid for an owner-scoped immutable revision. Blocked destinations are excluded from ranking and missing approved evaluators return Indeterminate.

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

destinationIds

required

Array<string>

>= 2 items <= 12 items

perturbations

required

Array

>= 1 items <= 35 items

One of:

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: nominal_return

delta

required

number

>= -0.5 <= 0.5

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: direct_real_return

delta

required

number

>= -0.5 <= 0.5

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: destination_inflation

delta

required

number

>= -0.5 <= 0.5

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: fx

initialShock

required

number

>= -0.9 <= 5

longRunShock

required

number

>= -0.9 <= 5

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: housing

multiplier

required

number

>= 0.1 <= 5

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: total_budget

multiplier

required

number

>= 0.1 <= 5

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: tax_rule_scenario

ruleScenarioId

required

string

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

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: visa_eligibility

destinationId

required

Unique identifier (UUID v4)

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

eligibility

required

string

Allowed values: ineligible blocked

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: withdrawal_rate

delta

required

number

>= -0.2 <= 0.2

object

object

id

required

string

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

label

required

string

>= 1 characters <= 120 characters

dimension

required

string

Allowed values: retirement_date

yearsDelta

required

integer

>= -30 <= 30

Responses

200

Completed or explicitly indeterminate 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: destination_rank_stability

result

required

One of:

object

object

ok

required

boolean

value

required

object

state

required

string

Allowed values: stable sensitive similar indeterminate

policy

required

object

version

required

string

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

higherScoreIsBetter

required

boolean

tieTolerance

required

number

topK

required

integer

> 0 <= 12

minValidCoverage

required

number

<= 1

minValidScenarios

required

integer

> 0 <= 35

stableMembershipThreshold

required

number

<= 1

stableOrderThreshold

required

number

<= 1

requestedPerturbations

required

integer

> 0 <= 35

validPerturbations

required

integer

<= 35

validCoverage

required

number

<= 1

sufficientEvidence

required

boolean

headlineDestinationId

required

Unique identifier (UUID v4)

string | null format: uuid

policyThresholdMet

required

boolean

baselineRanking

required

Array<object>

<= 12 items

object

destinationId

required

Unique identifier (UUID v4)

string format: uuid

score

required

number

rank

required

integer

> 0 <= 12

tied

required

boolean

scenarios

required

Array<object>

<= 35 items

object

perturbationId

required

string

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

dimension

required

string

Allowed values: nominal_return direct_real_return destination_inflation fx housing total_budget tax_rule_scenario visa_eligibility withdrawal_rate retirement_date

valid

required

boolean

ranking

required

Array<object>

<= 12 items

object

destinationId

required

Unique identifier (UUID v4)

string format: uuid

score

required

number

rank

required

integer

> 0 <= 12

tied

required

boolean

tieGroups

required

Array<Array<string>>

<= 12 items

excludedDestinationIds

required

Array<string>

<= 12 items

candidates

required

Array<object>

<= 12 items

object

destinationId

required

Unique identifier (UUID v4)

string format: uuid

topKMembership

required

number

<= 1

eligibleScenarioCount

required

integer

<= 35

medianRank

required

number | null

>= 1 <= 12

rankRange

required

array | null

meetsMembershipThreshold

required

boolean

pairwiseOrder

required

Array<object>

<= 66 items

object

a

required

Unique identifier (UUID v4)

string format: uuid

b

required

Unique identifier (UUID v4)

string format: uuid

comparableScenarioCount

required

integer

<= 35

aAboveB

required

number

<= 1

bAboveA

required

number

<= 1

tied

required

number

<= 1

breakEvenDiagnostics

required

Array<object>

<= 350 items

object

dimension

required

string

Allowed values: nominal_return direct_real_return destination_inflation fx housing total_budget tax_rule_scenario visa_eligibility withdrawal_rate retirement_date

leaderId

required

Unique identifier (UUID v4)

string format: uuid

challengerId

required

Unique identifier (UUID v4)

string format: uuid

kind

required

string

Allowed values: tie_at_tested_point flip_bracket

lowerMagnitude

required

number

upperMagnitude

required

number

perturbationIds

required

Array<string>

>= 1 items <= 2 items

exclusions

required

Array<object>

<= 12 items

object

destinationId

required

Unique identifier (UUID v4)

string format: uuid

scenarioIds

required

Array<string>

<= 36 items

reasonCodes

required

Array<string>

<= 32 items

reasonCodes

required

Array<string>

<= 32 items

object

object

ok

required

boolean

state

required

string

Allowed values: indeterminate

reasons

required

Array<string>

>= 1 items <= 32 items

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": "destination_rank_stability",
    "result": {
      "ok": true,
      "value": {
        "state": "stable",
        "headlineDestinationId": "550e8400-e29b-41d4-a716-446655440000",
        "baselineRanking": [
          {
            "destinationId": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "scenarios": [
          {
            "dimension": "nominal_return",
            "ranking": [
              {
                "destinationId": "550e8400-e29b-41d4-a716-446655440000"
              }
            ],
            "tieGroups": [
              [
                "550e8400-e29b-41d4-a716-446655440000"
              ]
            ],
            "excludedDestinationIds": [
              "550e8400-e29b-41d4-a716-446655440000"
            ]
          }
        ],
        "candidates": [
          {
            "destinationId": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "pairwiseOrder": [
          {
            "a": "550e8400-e29b-41d4-a716-446655440000",
            "b": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "breakEvenDiagnostics": [
          {
            "dimension": "nominal_return",
            "leaderId": "550e8400-e29b-41d4-a716-446655440000",
            "challengerId": "550e8400-e29b-41d4-a716-446655440000",
            "kind": "tie_at_tested_point"
          }
        ],
        "exclusions": [
          {
            "destinationId": "550e8400-e29b-41d4-a716-446655440000"
          }
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

400

Invalid perturbation 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"
    }
  ]
}