propositions

Add a proposition — proposed until a person decides

post/workspaces/{id}/questions/{questionId}/propositions

Request

  • Base URL: https://api.swingfactor.ai/v1
  • URL: https://api.swingfactor.ai/v1/workspaces/{id}/questions/{questionId}/propositions
  • Auth: HTTP bearer

Path parameters

idstring uuid required

The workspace's id (a UUID).

questionIdstring uuid required

The question's id (a UUID).

Headers

Idempotency-Keystring

Any unique string. The same key, method, path and body within 24 hours answers with the first response instead of creating again; the same key on a different request is 409 idempotency_key_reused.

Request body

namestring
statementstring required
claimType'fact' | 'estimate' | 'model-result' | 'proposal' | 'scenario' | 'interpretation' | 'unresolved' required

What kind of statement it is.

standing'possible' | 'probable' | 'demonstrated'

How far it is shown: possible, probable and demonstrated are three different things.

evidenceStrength'strong' | 'moderate' | 'weak' | 'contested' | 'unknown'

Defaults to unknown.

problemKind'epistemic' | 'capability' | 'normative'

Defaults to epistemic.

horizon'transition' | 'early' | 'medium' | 'long' | 'every'

The matched horizon: transition (Day One), early adjustment, medium term, long run, or every horizon. None: not stated — never every.

role'empirical' | 'mixed' | 'methodological' | 'normative'

Defaults to empirical.

switchingConditionstring
attribution'specific' | 'common'

Defaults to specific.

transmissionstring
effect'direction' | 'net' | 'forecast'

For a claim about an effect: its direction, the net effect, or a forecast — each needing more evidence than the last.

scenarioIdstring uuid
everyScenarioboolean

It holds whichever scenario happens. Never with a scenario. Neither: not stated.

dimensionIdstring uuid

The factor it establishes.

positioninteger

Response

The proposition, proposed.

idstring uuid required
workspaceIdstring uuid required
questionIdstring uuid required
namestring

What it is called wherever it is listed.

statementstring required
claimType'fact' | 'estimate' | 'model-result' | 'proposal' | 'scenario' | 'interpretation' | 'unresolved' required

What kind of statement it is.

standing'possible' | 'probable' | 'demonstrated'

How far it is shown: possible, probable and demonstrated are three different things.

evidenceStrength'strong' | 'moderate' | 'weak' | 'contested' | 'unknown' required

How well the evidence supports it — separately from its claim type.

problemKind'epistemic' | 'capability' | 'normative' required

While unresolved: investigate (epistemic), build capacity, or decide (normative).

horizon'transition' | 'early' | 'medium' | 'long' | 'every'

The matched horizon: transition (Day One), early adjustment, medium term, long run, or every horizon. None: not stated — never every.

role'empirical' | 'mixed' | 'methodological' | 'normative' required

Empirical and mixed propositions owe a switching condition; methodological and normative principles do not.

switchingConditionstring

What we would have to discover for the present assessment to change materially.

switchingStatus'untested' | 'tested-no-switch' | 'tested-partial-switch' | 'switched' | 'reopened' required

Whether its switching condition has been tested, and what came of it: untested, tested with no switch, partly switched, switched, or reopened by new evidence.

switchingTestedAtstring

When its switching status was last set; absent while untested. Stamped by the database.

switchingTestedByNamestring

Who set it.

switchingBasisstring

Why: the reason given with it.

reviewBystring

When it should be looked at again, YYYY-MM-DD; from that day it waits in To check.

priority'now' | 'next' | 'later'

A person's priority for it under the question's constraint; never set without one.

priorityReasonstring
upstreamChangedAtstring

When something it rests on changed after it was decided. Cleared once a person edits it, decides it again or says it still holds.

upstreamChangedFromstring uuid

The proposition it rests on that changed.

attribution'specific' | 'common' required

Common: arises under every option, and is counted against none. Specific: through a transmission some options have.

transmissionstring

How it reaches the options it bears on.

effect'direction' | 'net' | 'forecast'

For a claim about an effect: its direction, the net effect, or a forecast — each needing more evidence than the last.

scenarioIdstring uuid

The scenario it holds under. With neither this nor everyScenario, not stated.

everyScenarioboolean

It holds whichever scenario happens. Never with a scenario. Neither: not stated.

dimensionIdstring uuid

The factor it establishes, where it establishes one.

status'proposed' | 'accepted' | 'qualified' | 'unresolved' | 'rejected' required

Its verdict, which changes only by a person’s decision: accepted (it survives), qualified, unresolved or rejected.

decidedBystring uuid
decidedByNamestring
decidedAtstring
positioninteger required
createdBystring uuid
createdAtstring required
draftIdstring uuid

Set where SwingFactor drafted it.

updatedAtstring required

Example response

{
  "name": "Fiscal starting position",
  "statement": "GERS 2025-26 records a net fiscal balance of -10.9% of GDP."
}

Changes

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