---
title: "Save an explicit named residual scenario"
method: POST
path: "/api/v1/intelligence/scenarios"
tags: ["Property Intelligence"]
---

# Save an explicit named residual scenario

`POST /api/v1/intelligence/scenarios`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/intelligence/scenarios`
- Auth: HTTP bearer

Requires API-key or first-party session authentication and a current account in the default-off server cohort. Valid current membership does not require a new paid subscription. Existing API quotas still apply. Responses are private, no-store. No query parameters are used by this operation; its inputs are the strict JSON body. This contract does not indicate source activation, deployment or an SDK release. Retained objects are scoped to the current account and their creator; no caller-supplied account/user grant is accepted. Current source rights are checked for every read/use, independently of archived grants. Creates an immutable base/downside/upside revision linked to an owned readable run. A parent revision must belong to the same run and creator. Formula uses fixed-dollar profit and purchase-independent carry; no live values/default costs are invented. Negative residuals remain explicit. The JSON object is strict, bounded to 16,384 bytes, and costs must contain each of the five buckets once.

## Request body

- IntelligenceScenarioInput: All five unique cost buckets and a matching currency are required; explicitly enter zero. No inferred defaults. Only fixed-dollar profit and purchase-independent carry.
  - `run_id` string, required
  - `label` 'base' | 'downside' | 'upside', required
  - `parent_revision_id` string
  - `assumptions` object, required
    - `currency` string, required
    - `gross_completed_sale` string, required
    - `selling_costs` string, required
    - `costs` object[], required
      - `bucket` 'hard' | 'soft' | 'contingency' | 'carry' | 'other_nonland', required
      - `amount` string, required
      - `currency` string, required
    - `required_profit_dollars` string, required
    - `fixed_acquisition_costs` string, required
    - `acquisition_cost_rate` string, required
    - `profit_mode` 'fixed_dollars', required
    - `carry_mode` 'purchase_independent', required
    - `input_source` 'user_input', required

## Response `201`

Authorized result; unavailable/partial/stale states are explicit within the response. No live coverage is implied by this contract.

- IntelligenceScenarioRevision
  - `id` string, required
  - `run_id` string, required
  - `parent_revision_id` string, required
  - `label` 'base' | 'downside' | 'upside', required
  - `created_at` string, required
  - `assumptions` IntelligenceResidualAssumptions, required
    - `currency` string, required
    - `gross_completed_sale` string, required
    - `selling_costs` string, required
    - `costs` object[], required
      - `bucket` 'hard' | 'soft' | 'contingency' | 'carry' | 'other_nonland', required
      - `amount` string, required
      - `currency` string, required
    - `required_profit_dollars` string, required
    - `fixed_acquisition_costs` string, required
    - `acquisition_cost_rate` string, required
    - `profit_mode` 'fixed_dollars', required
    - `carry_mode` 'purchase_independent', required
    - `input_source` 'user_input', required
  - `result` IntelligenceCalculation, required
    - `definition` string, required
    - `status` 'available' | 'partial' | 'insufficient_data' | 'unavailable' | 'stale' | 'error', required
    - `reasons` string[], required
    - `metrics` object, required
    - `counts` object, required
    - `exclusions` object, required
    - `evidence_ids` string[], required
    - `context` object, required
      - `input_kind` 'observed' | 'user_assumptions' | 'unavailable', required
      - `requested_scope` object, nullable, required
        - `geography` string, required
        - `property_type` string, required
        - `currency` string, required
      - `actual_scope` object, nullable, required
        - `geography` string, required
        - `property_type` string, required
        - `currency` string, required
      - `query` object, nullable, required
        - `as_of` string, required
        - `knowledge_cutoff` string, required
      - `period` union, required
        - object
          - `kind` 'window', required
          - `window` object, required
            - `start` string, required
            - `end` string, required
        - object
          - `kind` 'snapshot', required
          - `at` string, required
        - object
          - `kind` 'comparison', required
          - `current` object, required
            - `start` string, required
            - `end` string, required
          - `previous` object, required
            - `start` string, required
            - `end` string, required
        - object
          - `kind` 'stock_flow', required
          - `snapshot_at` string, required
          - `flow` object, required
            - `start` string, required
            - `end` string, required
      - `metric_periods` object, required
      - `latest_observation_at` string, nullable, required
      - `source_as_of` string, nullable, required
      - `source_vintage` string, nullable, required
      - `history_complete` boolean, nullable, required

## Other responses

- `400`: Invalid, unknown or duplicate parameters; invalid time, source key or scenario assumptions.
- `401`: Authentication required, or supplied credential invalid. A rejected bearer does not fall back to a session.
- `402`: Existing API-key monthly quota exceeded; this feature adds no paid SKU.
- `403`: Current source rights do not permit the requested retained Intelligence use.
- `404`: Feature disabled, current account outside cohort, or requested retained object/parcel unavailable. Other creators' objects are not disclosed.
- `413`: Scenario JSON body exceeds 16,384 bytes.
- `429`: Existing API or concurrent-request limit exceeded.
- `500`: Unexpected service failure; internal details are withheld.
- `504`: Database query timeout.

---

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