openapi: 3.0.3
info:
  title: FinanceGPT Enterprise API
  version: 2.0.0
  description: >-
    Workspace-scoped FinanceGPT and EquityGPT intelligence API. Production and sandbox
    credentials are separate. Sandbox requests return deterministic fixtures and never read
    production workspace records.
servers:
  - url: https://financegpt.tools/api/v2
    description: FinanceGPT deployment
security:
  - bearerAuth: []
paths:
  /oauth/token:
    post:
      security: []
      summary: Issue an OAuth 2.0 client-credentials service token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [grant_type, client_id, client_secret]
              properties:
                grant_type: {type: string, enum: [client_credentials]}
                client_id: {type: string}
                client_secret: {type: string, format: password}
                scope: {type: string, description: Space-delimited subset of the client's scopes.}
      responses:
        '200': {description: Access token issued}
        '400': {description: Invalid grant or scope}
        '401': {description: Invalid client}
        '403': {description: API entitlement unavailable}
  /workspace:
    get:
      summary: Get the credential's FinanceGPT workspace
      x-financegpt-scope: workspace:read
      responses: {'200': {description: Workspace}}
  /ai-credits/balance:
    get:
      summary: Read the active workspace FinanceGPT AI Credit balance and subscription allocation
      x-financegpt-scope: ai:credits:read
      responses:
        '200': {description: FinanceGPT AI Credit wallet balance, reservation and included-allocation summary}
  /ai-credits/transactions:
    get:
      summary: Read the active workspace immutable FinanceGPT AI Credit ledger
      x-financegpt-scope: ai:credits:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 50}}
      responses:
        '200': {description: FinanceGPT AI Credit transaction history}
  /ai-credits/rates:
    get:
      summary: Read active FinanceGPT Managed AI Credit rate cards
      x-financegpt-scope: ai:credits:read
      responses:
        '200': {description: Active FinanceGPT model credit-consumption rate cards and runtime enforcement mode}
  /ai-credits/estimate:
    post:
      summary: Estimate the FinanceGPT AI Credit reservation for a Managed AI request without executing it
      x-financegpt-scope: ai:credits:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [financegpt_model, messages]
              properties:
                financegpt_model: {type: string, example: financegpt-intelligence}
                messages:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [role, content]
                    properties:
                      role: {type: string}
                      content: {}
                max_tokens: {type: integer, minimum: 1, maximum: 131072}
      responses:
        '200': {description: Estimated and reserved credit amounts plus current wallet capacity}
        '422': {description: Invalid model, message shape or rate-card configuration}
  /ai-credits/packs:
    get:
      summary: List active FinanceGPT AI Credit packs available to the active workspace
      x-financegpt-scope: ai:credits:read
      responses:
        '200': {description: Active administrator-configured FinanceGPT AI Credit packs and prepaid-service disclosure}
  /ai-credits/purchases:
    get:
      summary: Read verified FinanceGPT AI Credit purchase history for the active workspace
      x-financegpt-scope: ai:credits:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 50}}
      responses:
        '200': {description: Workspace AI Credit purchase history without payment-method secrets}
  /ai-credits/usage:
    get:
      summary: Read FinanceGPT Managed AI usage, forecast and utilization for the active workspace
      x-financegpt-scope: ai:credits:read
      parameters:
        - {in: query, name: period, schema: {type: string, enum: [day, week, month, quarter, year], default: month}}
      responses:
        '200': {description: Workspace usage totals, previous-period comparison, daily series, model/capability/provider mix and deterministic credit forecast}
  /ai-credits/controls:
    get:
      summary: Read workspace and caller FinanceGPT AI Credit spending controls
      x-financegpt-scope: ai:credits:read
      responses:
        '200': {description: Managed AI enablement, per-request/daily/weekly/monthly limits, utilization and forecast risk}
  /ai/models:
    get:
      summary: Read the FinanceGPT Managed AI model catalogue
      x-financegpt-scope: ai:models:read
      responses:
        '200': {description: FinanceGPT customer-facing managed model catalogue and availability}
  /ai/model-selections:
    get:
      summary: Read Universal Model Switching choices for the active workspace
      description: Returns Auto — FinanceGPT Native, eligible local language, permitted FinanceGPT managed models, administrator-enabled premium routes and valid workspace BYOK choices. Model selection affects eligible language generation only and never transfers deterministic calculation, policy, approval or Financial Actions authority to a language model.
      x-financegpt-scope: ai:models:read
      parameters:
        - {in: query, name: feature, schema: {type: string, enum: [copilot, knowledge, data_studio, client_intelligence, agent_spaces, api], default: api}}
      responses:
        '200': {description: Policy-filtered model-selection catalogue, availability and relative AI Credit tier}
  /ai/runtime:
    get:
      summary: Read the active workspace Managed AI runtime posture
      x-financegpt-scope: ai:models:read
      responses:
        '200': {description: Managed AI status, model availability and 30-day provider telemetry}
  /ai/byok/connections:
    get:
      summary: Read customer-managed AI provider connection status for the active workspace
      x-financegpt-scope: ai:connections:read
      responses:
        '200': {description: Workspace BYOK connection inventory, masked credential hints, validation state and capability declarations; plaintext credentials are never returned}
  /ai/byok/usage:
    get:
      summary: Read customer-managed AI provider usage for the active workspace
      x-financegpt-scope: ai:connections:read
      parameters:
        - {in: query, name: days, schema: {type: integer, minimum: 1, maximum: 365, default: 30}}
      responses:
        '200': {description: BYOK request, token, provider and status telemetry; provider billing remains directly between the customer and provider and FinanceGPT AI Credits are not charged}
  /ai/routing:
    get:
      summary: Read the active workspace Hybrid AI routing policy and explicit rules
      x-financegpt-scope: ai:routing:read
      responses:
        '200': {description: Managed AI/BYOK routing defaults, explicit fallback posture, data classification and rule metadata; no provider credentials are returned}
  /ai/routing/resolve:
    post:
      summary: Simulate a Hybrid AI routing decision without executing model inference
      x-financegpt-scope: ai:routing:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [purpose, data_classification]
              properties:
                purpose: {type: string, example: chat}
                capability: {type: string, example: chat}
                data_classification: {type: string, enum: [public, internal, confidential, restricted]}
                environment: {type: string, enum: [production, sandbox, development], default: production}
                financegpt_model: {type: string, example: financegpt-intelligence}
      responses:
        '200': {description: Dry-run routing result including runtime source, FinanceGPT model or BYOK connection, explicit fallback source and billing boundary; fallbacks_are_explicit is always true}
        '409': {description: No permitted runtime satisfies the active enterprise routing policy}
  /agents/spaces:
    get:
      summary: List production FinanceGPT Agent Spaces for the active workspace
      x-financegpt-scope: agents:spaces:read
      responses:
        '200': {description: Production Agent Spaces with promoted version, model, output and human-review policy}
  /agents/spaces/{uid}:
    get:
      summary: Read one production FinanceGPT Agent Space and its governed bindings
      x-financegpt-scope: agents:spaces:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Agent Space metadata and secret-free Knowledge, QLM and proposal-only MCP binding summary}
        '404': {description: Agent Space not found in this workspace}
  /agents/spaces/{uid}/runs:
    post:
      summary: Run a promoted FinanceGPT Agent Space
      x-financegpt-scope: agents:spaces:run
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
        - {in: header, name: Idempotency-Key, required: false, description: Optional idempotency key for queued Agent Space execution, schema: {type: string, maxLength: 191}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt: {type: string, maxLength: 50000}
                execution_mode: {type: string, enum: [auto, sync, async], default: auto}
                model_selection: {type: string, example: auto_native, description: NI6 per-run model choice; may be policy-locked when a QLM profile pins an explicit connection}
      responses:
        '201': {description: Synchronous governed Agent Space run}
        '202': {description: Agent Space execution accepted by the asynchronous worker fabric}
        '503': {description: Asynchronous execution was required but no asynchronous queue driver is available}
        '429': {description: Runtime or Agent queue capacity is temporarily exhausted; retry after the Retry-After interval}
        '409': {description: Agent Space cannot run under the active version, access, routing or AI Credit policy}
  /agents/runs/{runUid}:
    get:
      summary: Read one governed FinanceGPT Agent Space run
      x-financegpt-scope: agents:spaces:read
      parameters:
        - {in: path, name: runUid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Agent Space run output, hashes, evidence steps, runtime identity and human-review state; financial_action_executed is false}
        '404': {description: Agent Space run not found in this workspace}
  /agents/executions/{uid}:
    get:
      summary: Read one queued Agent Space execution
      x-financegpt-scope: agents:spaces:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Queued, running, completed or failed execution state and linked governed run UID}
        '404': {description: Queued execution not found in this workspace}
  /agents/tools:
    get:
      summary: List FinanceGPT MCP tools and credential grant state
      x-financegpt-scope: agents:mcp:read
      responses: {'200': {description: Agent tool catalogue}}
  /agents/invocations:
    get:
      summary: List hash-only MCP invocation audit metadata for this agent credential
      x-financegpt-scope: agents:mcp:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
      responses: {'200': {description: Agent invocation audit rows}}
  /financial/snapshots:
    get:
      summary: List normalized connected financial snapshots
      x-financegpt-scope: financial:read
      parameters:
        - {in: query, name: provider, schema: {type: string}}
        - {in: query, name: from, schema: {type: string, format: date}}
        - {in: query, name: to, schema: {type: string, format: date}}
        - {in: query, name: after_id, schema: {type: integer}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 50}}
      responses: {'200': {description: Financial snapshots}}
  /financial/transactions:
    get:
      summary: List normalized connected financial transactions
      x-financegpt-scope: financial:read
      parameters:
        - {in: query, name: provider, schema: {type: string}}
        - {in: query, name: direction, schema: {type: string}}
        - {in: query, name: status, schema: {type: string}}
        - {in: query, name: from, schema: {type: string, format: date}}
        - {in: query, name: to, schema: {type: string, format: date}}
        - {in: query, name: after_id, schema: {type: integer}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 200, default: 100}}
      responses: {'200': {description: Financial transactions}}
  /planning/forecasts:
    get:
      summary: List governed FinanceGPT forecasts
      x-financegpt-scope: planning:read
      responses: {'200': {description: Forecasts}}
    post:
      summary: Generate and persist a backtest-selected forecast
      x-financegpt-scope: planning:forecast:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [metric]
              properties:
                metric: {type: string}
                company_id: {type: integer, nullable: true}
                horizon: {type: integer, minimum: 1, maximum: 24, default: 6}
                reason: {type: string, maxLength: 191}
      responses:
        '201': {description: Forecast generated}
        '422': {description: Insufficient history or invalid input}
  /workflows/runs:
    get:
      summary: List finance workflow runs, task status and reporting-pack status
      x-financegpt-scope: workflow:read
      responses: {'200': {description: Workflow runs}}
  /workflows/events/{key}:
    post:
      summary: Submit an idempotent encrypted event into the FinanceGPT workflow runtime
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: key, required: true, schema: {type: string}}
        - {in: header, name: Idempotency-Key, required: true, schema: {type: string, maxLength: 191}}
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                template_id: {type: integer, nullable: true}
                payload: {type: object, additionalProperties: true}
      responses:
        '201': {description: Event accepted, deduplicated and optionally attached to a workflow run; raw payload is encrypted at rest}
        '422': {description: Missing idempotency key or invalid event payload}
        '429': {description: Workspace workflow execution capacity is temporarily exhausted}
  /workflows/runtime/{id}:
    get:
      summary: Read durable node execution state for a finance workflow run
      x-financegpt-scope: workflow:read
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses:
        '200': {description: Workflow node graph execution state, waits and errors}
        '404': {description: Workflow run not found in this workspace}
  /workflow-studio:
    get:
      summary: Read Workflow Studio templates, durable runs and catalogue status
      x-financegpt-scope: workflow:read
      responses:
        '200': {description: Workflow Studio workspace overview}
  /workflow-studio/use-cases:
    get:
      summary: List the canonical FinanceGPT workflow use-case catalogue
      x-financegpt-scope: workflow:read
      responses:
        '200': {description: 55 governed reference use cases across 11 segments}
  /workflow-studio/use-cases/{uid}/install:
    post:
      summary: Install a use case as an editable Workflow Studio draft
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '201': {description: Draft workflow installed; no financial authority granted}
  /workflow-studio/templates/{id}/runs:
    post:
      summary: Start an idempotent durable workflow run
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses:
        '202': {description: Workflow run accepted by the financegpt-workflows queue}
  /workflow-studio/events/{key}:
    post:
      summary: Trigger a configured Workflow Studio event idempotently
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: key, required: true, schema: {type: string}}
        - {in: header, name: Idempotency-Key, required: true, schema: {type: string, maxLength: 191}}
      responses:
        '202': {description: Durable Workflow Studio run accepted}
        '422': {description: Idempotency-Key is missing or payload is invalid}
  /workflow-studio/runs/{uid}:
    get:
      summary: Read durable Workflow Studio state and node evidence
      x-financegpt-scope: workflow:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Durable workflow run state}
  /workflow-studio/runs/{uid}/{action}:
    post:
      summary: Pause, resume, cancel or replay a durable workflow run
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
        - {in: path, name: action, required: true, schema: {type: string, enum: [pause, resume, cancel, replay]}}
      responses:
        '202': {description: Durable control action recorded}
  /workflow-studio/nodes/{uid}/review:
    post:
      summary: Record a human review for a governed workflow node
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '202': {description: Node review recorded; Financial Action creation remains separately governed}
  /investment/companies/{symbol}:
    get:
      summary: Read governed Company 360 investment evidence
      x-financegpt-scope: investment:read
      parameters: [{in: path, name: symbol, required: true, schema: {type: string}}]
      responses: {'200': {description: Company profile and evidence available to the workspace}}
  /investment/derivatives/options:
    get:
      summary: Analyze an observed option chain with IV, Greeks, smile and term-structure evidence
      description: >-
        Uses the FinanceGPT Market Data Gateway. Yahoo Free is preferred and quota-governed Axesso
        may be used only when the free chain is unavailable and paid fallback is permitted. Returned
        contracts are observed/provider-backed; no synthetic option chain is substituted.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: symbol, required: true, schema: {type: string, maxLength: 40}}
        - {in: query, name: region, schema: {type: string, maxLength: 8, default: US}}
        - {in: query, name: expiration, schema: {type: string, format: date}}
        - {in: query, name: risk_free_rate_pct, schema: {type: number, minimum: -25, maximum: 100, default: 0}}
        - {in: query, name: dividend_yield_pct, schema: {type: number, minimum: -25, maximum: 100, default: 0}}
        - {in: query, name: paid_fallback, schema: {type: boolean, default: true}}
      responses:
        '200': {description: Observed option-chain analysis with source/freshness hashes and deterministic quantitative analytics}
        '422': {description: Invalid symbol or analysis parameters}
        '503': {description: Observed market data unavailable under configured provider/freshness policy}
  /investment/derivatives/futures:
    get:
      summary: Analyze an observed futures contract curve
      description: >-
        Reads the quota-governed Axesso futures chain through the FinanceGPT Market Data Gateway and
        derives front-contract spreads plus descriptive contango/backwardation diagnostics.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: symbol, required: true, schema: {type: string, maxLength: 40}}
        - {in: query, name: region, schema: {type: string, maxLength: 8, default: US}}
      responses:
        '200': {description: Observed futures curve with provider/freshness evidence}
        '503': {description: Axesso unavailable, disabled or outside quota policy}
  /investment/derivatives/strategy:
    post:
      summary: Calculate a deterministic multi-leg option expiry payoff grid
      x-financegpt-scope: investment:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [legs]
              properties:
                spot: {type: number, minimum: 0.00000001}
                legs:
                  type: array
                  minItems: 1
                  maxItems: 8
                  items:
                    type: object
                    required: [option_type, side, strike, premium, contracts]
                    properties:
                      option_type: {type: string, enum: [call, put]}
                      side: {type: string, enum: [long, short]}
                      strike: {type: number, minimum: 0.00000001}
                      premium: {type: number, minimum: 0}
                      contracts: {type: integer, minimum: 1, maximum: 10000}
                      multiplier: {type: integer, minimum: 1, maximum: 100000, default: 100}
      responses:
        '200': {description: Deterministic expiry payoff grid and approximate break-even crossings; no order created}
  /investment/derivatives/snapshots:
    get:
      summary: Read sealed observed-derivatives evidence snapshots
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: symbol, schema: {type: string, maxLength: 40}}
        - {in: query, name: instrument_type, schema: {type: string, enum: [options, futures]}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses:
        '200': {description: Workspace-scoped derived derivatives summaries/surfaces and cryptographic evidence hashes}
  /investment/derivatives/synthetic-options:
    post:
      summary: Generate a sealed FINANCEGPT SYNTHETIC option chain from a promoted LQM
      description: >-
        Uses a human-promoted derivatives-surface LQM plus a typed numeric conditioning envelope to
        generate a synthetic implied-volatility surface. FinanceGPT applies deterministic static
        no-arbitrage validation and repair before deriving option prices and Greeks. Outputs are
        explicitly synthetic, non-observed and never execution eligible or a substitute for observed market data.
      x-financegpt-scope: investment:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [symbol, promotion_uid]
              properties:
                symbol: {type: string, maxLength: 40}
                promotion_uid: {type: string, maxLength: 64}
                spot: {type: number, minimum: 0.00000001, description: Optional manual spot override; otherwise governed Yahoo data is used}
                risk_free_rate_pct: {type: number, minimum: -25, maximum: 100, default: 0}
                dividend_yield_pct: {type: number, minimum: -25, maximum: 100, default: 0}
                realized_vol_pct: {type: number, minimum: 0.1, maximum: 500}
                garch_vol_pct: {type: number, minimum: 0.1, maximum: 500}
                regime_code: {type: number, minimum: -1, maximum: 1, default: 0}
                sector_factor: {type: number, minimum: -5, maximum: 5, default: 0}
                theme_factor: {type: number, minimum: -5, maximum: 5, default: 0}
                moneyness_min: {type: number, minimum: 0.5, maximum: 1, default: 0.75}
                moneyness_max: {type: number, minimum: 1, maximum: 2, default: 1.25}
                moneyness_steps: {type: integer, minimum: 5, maximum: 31, default: 11}
                maturities_days:
                  type: array
                  minItems: 2
                  maxItems: 10
                  items: {type: integer, minimum: 7, maximum: 1095}
                  example: [30, 60, 90, 180, 365]
                seed: {type: integer, minimum: 0, maximum: 2147483647, default: 42}
                sample_count: {type: integer, minimum: 1, maximum: 20, default: 8}
      responses:
        '201': {description: Sealed synthetic option-chain run with LQM Evidence Packet, conditioning, no-arbitrage and derived-chain SHA-256 evidence}
        '422': {description: Invalid conditioning input or no eligible promoted derivatives-surface LQM}
        '503': {description: Required governed market data or LQM runtime unavailable}
  /investment/derivatives/synthetic-options/runs:
    get:
      summary: Read sealed FINANCEGPT SYNTHETIC option-chain runs
      description: Returns workspace-scoped synthetic runs and cryptographic evidence. Synthetic outputs remain non-executable.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: symbol, schema: {type: string, maxLength: 40}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses:
        '200': {description: Workspace-scoped sealed synthetic option-chain evidence}
  /investment/portfolios/{portfolio}/generative-markets:
    post:
      summary: Generate an evidence-sealed synthetic counterfactual market scenario for a portfolio
      description: >-
        Uses an approved FinanceGPT time-series generative model to produce multi-step market-factor paths,
        then deterministically derives yield, credit, volatility and FX curve views and applies terminal
        factor states only through verified portfolio/security sensitivities. Sample quantiles are descriptive
        statistics over generated counterfactuals, not probabilities, forecasts or confidence intervals.
        Outputs are synthetic and never execution eligible.
      x-financegpt-scope: investment:run
      parameters:
        - {in: path, name: portfolio, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [regime]
              properties:
                regime: {type: string, enum: [contraction, neutral, expansion]}
                sample_count: {type: integer, minimum: 1, maximum: 20, default: 8}
                horizon: {type: integer, minimum: 1, maximum: 12, default: 6}
                seed: {type: integer, minimum: 0, maximum: 2147483647, default: 42}
                base_volatility_pct: {type: number, minimum: 0.1, maximum: 500, default: 20}
                base_rate_pct: {type: number, minimum: -25, maximum: 100, default: 4}
                yield_curve_slope_bps_per_year: {type: number, minimum: -1000, maximum: 1000, default: 20}
                base_credit_spread_bps: {type: number, minimum: 0, maximum: 10000, default: 150}
                credit_curve_slope_bps_per_year: {type: number, minimum: -1000, maximum: 1000, default: 10}
                base_fx_level: {type: number, minimum: 0.00000001, maximum: 1000000, default: 1}
                stress:
                  type: object
                  properties:
                    equity_pct: {type: number, minimum: -100, maximum: 1000}
                    fx_pct: {type: number, minimum: -100, maximum: 1000}
                    rates_bps: {type: number, minimum: -10000, maximum: 10000}
                    credit_bps: {type: number, minimum: -10000, maximum: 10000}
                    commodity_pct: {type: number, minimum: -100, maximum: 1000}
                    volatility_pct: {type: number, minimum: -100, maximum: 1000}
      responses:
        '201': {description: Evidence-sealed synthetic generative market run with paths, deterministic curve views and portfolio counterfactual sample distribution}
        '422': {description: Invalid conditioning input}
        '503': {description: Approved generative model, synchronized feature vector or generative runtime unavailable}
  /investment/generative-markets/runs:
    get:
      summary: Read evidence-sealed generative market scenario runs
      description: Returns workspace-scoped synthetic counterfactual runs and SHA-256 evidence. Outputs remain non-executable.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, schema: {type: string}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses:
        '200': {description: Workspace-scoped generative market scenario evidence}
  /investment/ontology:
    get:
      summary: Read the published FinanceGPT Dynamic Industry Ontology
      description: >-
        Returns the workspace-scoped published five-tier controlled taxonomy, taxonomy-version evidence,
        exposure semantics and human-gated taxonomy-evolution state. IM5 is native-first and does not require
        an LLM. Taxonomy publication is never automatic.
      x-financegpt-scope: investment:read
      responses:
        '200': {description: Published taxonomy state, tier labels and governed candidate-review metadata}
  /investment/ontology/companies/{symbol}:
    get:
      summary: Read source-backed thematic exposure for a company
      description: >-
        Returns business-activity facts extracted from existing Company 360 evidence plus version-pinned
        economic, strategic and activity exposure components. Exposure weights are evidence-backed analytical
        classifications, not investment recommendations.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: symbol, required: true, schema: {type: string, maxLength: 32}}
      responses:
        '200': {description: Company activity facts and thematic exposures for the current published taxonomy}
        '422': {description: Invalid security symbol}
  /investment/ontology/companies/{symbol}/refresh:
    post:
      summary: Extract and classify company activity against the published ontology
      description: >-
        Reuses source-backed Company 360 evidence, performs deterministic FinanceGPT native lexical extraction,
        maps facts through the published hierarchical taxonomy and writes SHA-256-sealed exposure evidence.
        No third-party market-data call, LLM call, investment action or Financial Action is performed.
      x-financegpt-scope: investment:run
      parameters:
        - {in: path, name: symbol, required: true, schema: {type: string, maxLength: 32}}
      responses:
        '201': {description: Source-backed fact extraction and versioned exposure refresh result}
        '422': {description: Invalid symbol or ontology input}
        '503': {description: Published ontology or required Company 360 evidence unavailable}
  /investment/ontology/nodes/{node}/universe:
    get:
      summary: Rank the classified company universe by one controlled taxonomy node
      description: >-
        Returns evidence-backed company rankings for a taxonomy node using composite, economic, strategic,
        activity and confidence fields. This controlled-node universe remains available as a low-level taxonomy endpoint. IM6 Concept2Universe adds
        governed free-text decomposition, saved universes, investability filters and non-executable handoffs.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: node, required: true, schema: {type: integer, minimum: 1}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 250, default: 50}}
      responses:
        '200': {description: Taxonomy-node ranked universe with exposure components and evidence hashes}
        '503': {description: Published taxonomy unavailable}
  /investment/themes:
    get:
      summary: Read saved FinanceGPT thematic universes
      description: >-
        Returns workspace-scoped Concept2Universe discovery state and saved taxonomy-version-pinned thematic
        universes. Free-text decomposition is native-first and deterministic by default; results are thematic
        relevance evidence, not expected-return forecasts or investment recommendations.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: universe_id, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: Saved thematic-universe summaries and optional selected universe evidence}
  /investment/themes/discover:
    post:
      summary: Discover and save an evidence-backed thematic universe from free text
      description: >-
        Maps the concept to non-overlapping branches of the current published Dynamic Industry Ontology,
        ranks source-backed IM5 company exposures and applies explicit profile/provenance investability filters.
        No live market-data call, LLM requirement, Financial Action or trade execution is introduced by this endpoint.
      x-financegpt-scope: investment:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [concept]
              properties:
                name: {type: string, maxLength: 191}
                concept: {type: string, minLength: 3, maxLength: 1000}
                exchanges: {type: array, maxItems: 50, items: {type: string, maxLength: 40}}
                countries: {type: array, maxItems: 50, items: {type: string, maxLength: 80}}
                currencies: {type: array, maxItems: 20, items: {type: string, maxLength: 8}}
                restricted_symbols: {type: array, maxItems: 250, items: {type: string, maxLength: 32}}
                require_company_profile: {type: boolean, default: false}
                min_relevance: {type: number, minimum: 0, maximum: 1, default: 0.01}
                min_confidence: {type: number, minimum: 0, maximum: 1, default: 0}
                min_verified_facts: {type: integer, minimum: 0, maximum: 100000, default: 0}
                max_results: {type: integer, minimum: 1, maximum: 250, default: 50}
      responses:
        '201': {description: Saved taxonomy-version-pinned thematic universe with decomposition and ranked members}
        '422': {description: Invalid concept or investability-filter input}
        '503': {description: Published ontology unavailable or concept cannot be mapped to the controlled taxonomy}
  /investment/themes/universes/{universe}:
    get:
      summary: Read one saved thematic universe and its evidence
      description: >-
        Returns the immutable concept text, controlled taxonomy decomposition, ranked member evidence,
        investability snapshots and prior watchlist/model-portfolio handoffs for one workspace-scoped universe.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: universe, required: true, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: Saved thematic-universe evidence}
        '404': {description: Universe unavailable in the active workspace}
  /investment/themes/universes/{universe}/watchlist:
    post:
      summary: Hand a saved thematic universe to an investment watchlist
      description: >-
        Copies ranked members to the existing watchlist workflow with universe/member evidence hashes.
        This creates research state only and does not create, approve or execute a Financial Action.
      x-financegpt-scope: investment:run
      parameters:
        - {in: path, name: universe, required: true, schema: {type: integer, minimum: 1}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: {type: string, maxLength: 191}
                limit: {type: integer, minimum: 1, maximum: 100, default: 50}
      responses:
        '201': {description: Watchlist created from the saved thematic universe}
        '503': {description: Thematic-universe handoff unavailable}
  /investment/themes/universes/{universe}/model-portfolio:
    post:
      summary: Hand a saved thematic universe to a draft model portfolio
      description: >-
        Creates a draft model portfolio using thematic-relevance or equal weights. Existing model-portfolio
        governance approval remains mandatory before rebalance use; this endpoint does not place trades or create Financial Actions.
      x-financegpt-scope: investment:run
      parameters:
        - {in: path, name: universe, required: true, schema: {type: integer, minimum: 1}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: {type: string, maxLength: 191}
                limit: {type: integer, minimum: 2, maximum: 30, default: 20}
                weighting: {type: string, enum: [relevance, equal], default: relevance}
                benchmark_symbol: {type: string, maxLength: 32}
      responses:
        '201': {description: Draft model portfolio created with content hash and approval-required state}
        '503': {description: Thematic-universe handoff unavailable}
  /investment/construction/runs:
    get:
      summary: Read governed Portfolio Construction 2.0 runs
      description: Returns workspace-scoped construction evidence including selected method, CVaR/turnover metrics and SHA-256 evidence hashes. No run authorises execution.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, required: false, schema: {type: string}}
        - {in: query, name: limit, required: false, schema: {type: integer, minimum: 1, maximum: 100, default: 30}}
      responses:
        '200': {description: Construction run summaries}
  /investment/construction/runs/{uid}:
    get:
      summary: Read one Portfolio Construction 2.0 evidence record
      description: Returns the sealed request, observed market inputs, candidates, constraint evidence, selected candidate and research-only synthetic-options comparison where present.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Construction evidence record}
        '404': {description: Construction run not found in the active workspace}
  /investment/portfolios/{portfolio}/construct:
    post:
      summary: Run governed Portfolio Construction 2.0
      description: Runs observed-data portfolio construction with CVaR, tracking error, risk budgets, Black-Litterman, thematic bounds, turnover/cost and verified tax-lot awareness. Fresh observed option IV may be used as a risk floor. Synthetic option surfaces are research comparison only and cannot select the model portfolio or execute a Financial Action.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [symbols]
              properties:
                symbols: {type: array, minItems: 2, maxItems: 30, items: {type: string}}
                restricted_symbols: {type: array, maxItems: 30, items: {type: string}}
                objective: {type: string, enum: [balanced, min_volatility, max_expected_return, cvar_95, tracking_error, risk_budget, black_litterman]}
                max_position_pct: {type: number, minimum: 1, maximum: 100}
                risk_aversion: {type: number, minimum: 0.01, maximum: 100}
                history_months: {type: integer, minimum: 12, maximum: 120}
                benchmark_symbol: {type: string, maxLength: 32}
                cvar_alpha_pct: {type: number, minimum: 80, maximum: 99.5, default: 95}
                max_turnover_pct: {type: number, minimum: 0, maximum: 200, default: 100}
                transaction_cost_bps: {type: number, minimum: 0, maximum: 1000, default: 10}
                min_monthly_dollar_volume_usd: {type: number, minimum: 0, default: 0}
                tax_rate_pct: {type: number, minimum: 0, maximum: 100}
                derivatives_mode: {type: string, enum: [none, observed_risk, synthetic_research], default: none}
                risk_budgets: {type: object, additionalProperties: {type: number, minimum: 0.00000001}}
                black_litterman_views_pct: {type: object, additionalProperties: {type: number, minimum: -100, maximum: 1000}}
                min_weights_pct: {type: object, additionalProperties: {type: number, minimum: 0, maximum: 100}}
                max_weights_pct: {type: object, additionalProperties: {type: number, minimum: 0, maximum: 100}}
                theme_constraints:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      min_pct: {type: number, minimum: 0, maximum: 100}
                      max_pct: {type: number, minimum: 0, maximum: 100}
                create_model_portfolio: {type: boolean}
                model_name: {type: string, maxLength: 191}
      responses:
        '201': {description: Construction evidence created; no order placed}
        '422': {description: Invalid input, infeasible constraints or insufficient governed observed-market evidence}
  /investment/risk-compliance/runs:
    get:
      summary: Read Institutional Risk & Compliance 2.0 runs
      description: Returns workspace-scoped observed-data risk evidence including historical VaR/ES, theme-factor component risk, liquidity, concentration, derivative context and investment mandate/risk-policy control status. This is not a legal compliance determination and does not authorise execution.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, required: false, schema: {type: string}}
        - {in: query, name: limit, required: false, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses:
        '200': {description: Institutional risk run summaries}
  /investment/risk-compliance/runs/{uid}:
    get:
      summary: Read one Institutional Risk & Compliance 2.0 evidence record
      description: Returns one SHA-256-sealed institutional risk record from the active workspace.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Institutional risk evidence record}
        '404': {description: Risk run not found in the active workspace}
  /investment/portfolios/{portfolio}/risk-compliance:
    post:
      summary: Generate Institutional Risk & Compliance 2.0 evidence
      description: Generates observed-data historical VaR/ES, liquidity and concentration risk, includes saved IM7 theme-factor risk when available, attaches observed IM2 derivatives-market context, aggregates derivative Greeks only from explicit supplied position inputs, and refreshes configured investment mandate controls. No synthetic market data or Financial Action execution is permitted.
      x-financegpt-scope: investment:run
      parameters:
        - {in: path, name: portfolio, required: true, schema: {type: string}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                benchmark_symbol: {type: string, maxLength: 32}
                history_months: {type: integer, minimum: 12, maximum: 120, default: 36}
                derivative_positions:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    required: [symbol, quantity]
                    properties:
                      symbol: {type: string, maxLength: 32}
                      quantity: {type: number}
                      multiplier: {type: number, minimum: 0, default: 100}
                      delta: {type: number}
                      gamma: {type: number}
                      vega: {type: number}
                      theta: {type: number}
                      option_market_value_usd: {type: number}
      responses:
        '201': {description: Institutional risk evidence created; no order placed or Financial Action executed}
        '503': {description: Institutional risk evidence unavailable because required observed data or portfolio valuation is missing}
  /investment/portfolios/{portfolio}/scenarios:
    post:
      summary: Run a deterministic governed portfolio stress scenario
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                global_price_pct: {type: number, minimum: -100, maximum: 1000}
                symbols: {type: object, additionalProperties: {type: number}}
                factors: {type: object, additionalProperties: {type: number}}
      responses: {'201': {description: Scenario run with source and result hashes}}
  /investment/portfolios/{portfolio}/performance:
    get:
      summary: Read evidence-linked portfolio time-weighted performance
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: portfolio, required: true, schema: {type: string}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 50, default: 12}}
      responses: {'200': {description: Performance runs and valuation subperiod observations}}
  /investment/portfolios/{portfolio}/performance/observations:
    post:
      summary: Record a valuation subperiod and explicit external cash flow for portfolio performance
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [period_start, period_end, opening_value, closing_value, flow_timing, currency, source_type]
              properties:
                period_start: {type: string, format: date}
                period_end: {type: string, format: date}
                opening_value: {type: number, minimum: 0.00000001}
                closing_value: {type: number, minimum: 0}
                external_flow: {type: number, default: 0}
                flow_timing: {type: string, enum: [start, end]}
                currency: {type: string, maxLength: 8}
                source_type: {type: string, enum: [manual, custodian, provider, import]}
                source_reference: {type: string, maxLength: 191}
      responses: {'201': {description: Evidence-hashed performance observation}}
  /investment/portfolios/{portfolio}/performance/calculate:
    post:
      summary: Geometrically chain-link non-overlapping portfolio subperiod returns
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                period_start: {type: string, format: date}
                period_end: {type: string, format: date}
      responses:
        '201': {description: Time-weighted return, annualized return when appropriate, drawdown and methodology}
        '422': {description: Missing, overlapping or mixed-currency observations}
  /investment/portfolios/{portfolio}/tax-lots:
    get:
      summary: List governed tax-lot records for an adopted portfolio
      x-financegpt-scope: investment:read
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      responses: {'200': {description: Tax lots and verification provenance}}
  /investment/portfolios/{portfolio}/tax-harvest:
    post:
      summary: Create a tax-harvest proposal without executing a trade
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tax_regime]
              properties:
                tax_regime: {type: string, maxLength: 80}
                jurisdiction: {type: string, maxLength: 80}
                tax_rate_pct: {type: number, minimum: 0, maximum: 100}
                minimum_loss_usd: {type: number, minimum: 0}
                restriction_window_days: {type: integer, minimum: 0, maximum: 366}
                replacement_symbols: {type: array, items: {type: string}}
      responses: {'201': {description: Draft tax-harvest proposal; financial_action_executed is false}}
  /investment/execution/batches:
    get:
      summary: List governed investment execution batches
      x-financegpt-scope: investment:read
      responses: {'200': {description: Workspace execution batches and reconciliation state}}
    post:
      summary: Create an execution batch from an approved rebalance proposal
      x-financegpt-scope: investment:execute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rebalance_proposal_id, connector_id]
              properties:
                rebalance_proposal_id: {type: integer}
                connector_id: {type: integer}
                autonomy_mandate_uid: {type: string, format: uuid}
      responses: {'201': {description: Execution batch created; approval or mandate boundaries still apply}}
  /investment/execution/batches/{uid}/submit:
    post:
      summary: Submit an investment order batch for approval
      x-financegpt-scope: investment:execute
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Batch submitted for approval}}
  /investment/execution/batches/{uid}/execute:
    post:
      summary: Execute an approved governed investment order batch
      x-financegpt-scope: investment:execute
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses:
        '200': {description: Provider submission result or sandbox simulation}
        '422': {description: Rejected or uncertain execution outcome}
  /investment/execution/batches/{uid}/reconcile:
    post:
      summary: Reconcile an investment execution batch with broker/custodian evidence
      x-financegpt-scope: investment:execute
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Reconciled execution state}}
  /investment/risk:
    get:
      summary: List EquityGPT Professional risk snapshots
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, schema: {type: string}}
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses: {'200': {description: Investment risk snapshots}}
  /investment/reports:
    get:
      summary: List approved/finalized investment client reports
      x-financegpt-scope: investment:read
      responses: {'200': {description: Approved client reports}}
  /benchmarking/comparisons:
    get:
      summary: List published privacy-safe benchmark comparisons
      x-financegpt-scope: benchmark:read
      parameters:
        - {in: query, name: period_key, schema: {type: string}}
        - {in: query, name: metric_key, schema: {type: string}}
      responses: {'200': {description: Published comparisons only}}
  /intelligence/summary:
    get:
      summary: Retrieve an embedded cross-domain FinanceGPT intelligence summary
      x-financegpt-scope: intelligence:read
      responses: {'200': {description: Workspace intelligence summary}}
  /ml/models:
    get:
      summary: List approved active FinanceGPT ML model cards available to the workspace
      x-financegpt-scope: ml:read
      responses: {'200': {description: Active model registry}}
  /ml/anomaly:
    post:
      summary: Run approved financial anomaly inference on the latest synchronized derived feature vector
      x-financegpt-scope: ml:inference
      responses:
        '201': {description: Anomaly inference result}
        '409': {description: Approved model or synchronized features unavailable}
  /ml/scenarios:
    post:
      summary: Generate model-sampled financial stress scenarios from an approved VAE
      x-financegpt-scope: ml:inference
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                samples: {type: integer, minimum: 1, maximum: 20, default: 5}
                stress: {type: object, additionalProperties: {type: number}}
      responses:
        '201': {description: Generated scenario samples; not forecasts or probabilities}
        '409': {description: Approved model or synchronized features unavailable}
  /data/datasets:
    get:
      summary: List datasets currently licensed for FinanceGPT API redistribution
      x-financegpt-scope: data:reference:read
      responses: {'200': {description: Redistributable dataset catalogue}}
  /data/instruments:
    get:
      summary: Search the canonical FinanceGPT securities master
      x-financegpt-scope: data:reference:read
      responses: {'200': {description: Canonical instruments}}
  /data/instruments/{uid}:
    get:
      summary: Get a canonical instrument, issuer, venue and identifiers
      x-financegpt-scope: data:reference:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Instrument profile}}
  /data/instruments/{uid}/prices:
    get:
      summary: Get licence-governed normalized price history
      x-financegpt-scope: data:market:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Price bars with provenance}}
  /data/instruments/{uid}/fundamentals:
    get:
      summary: Get standardized fundamental facts
      x-financegpt-scope: data:fundamentals:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Fundamental facts with provenance}}
  /data/instruments/{uid}/corporate-actions:
    get:
      summary: Get normalized corporate actions
      x-financegpt-scope: data:market:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Corporate actions}}
  /data/economics/series:
    get:
      summary: Search licence-governed economic series
      x-financegpt-scope: data:economics:read
      responses: {'200': {description: Economic series}}
  /data/economics/series/{key}:
    get:
      summary: Get an economic series profile
      x-financegpt-scope: data:economics:read
      parameters: [{in: path, name: key, required: true, schema: {type: string}}]
      responses: {'200': {description: Economic series profile}}
  /data/economics/series/{key}/observations:
    get:
      summary: Get economic observations and vintages
      x-financegpt-scope: data:economics:read
      parameters: [{in: path, name: key, required: true, schema: {type: string}}]
      responses: {'200': {description: Economic observations with vintages}}
  /quant/features:
    get:
      summary: List governed FinanceGPT point-in-time feature definitions
      x-financegpt-scope: quant:features:read
      responses: {'200': {description: Feature catalogue}}
  /quant/features/{key}:
    get:
      summary: Get one governed financial feature definition
      x-financegpt-scope: quant:features:read
      parameters: [{in: path, name: key, required: true, schema: {type: string}}]
      responses: {'200': {description: Feature definition and methodology}}
  /quant/features/{key}/values:
    get:
      summary: Get look-ahead-safe API-releasable feature values for a canonical instrument
      x-financegpt-scope: quant:features:read
      parameters:
        - {in: path, name: key, required: true, schema: {type: string}}
        - {in: query, name: instrument_uid, required: true, schema: {type: string, format: uuid}}
      responses: {'200': {description: Point-in-time feature values with lineage}}
  /quant/projects:
    get:
      summary: List workspace quantitative research projects
      x-financegpt-scope: quant:research:read
      responses: {'200': {description: Workspace research projects}}
  /quant/research/snapshots:
    post:
      summary: Generate a sealed point-in-time research feature matrix
      x-financegpt-scope: quant:research:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [project_id, as_of_date]
              properties:
                project_id: {type: integer}
                as_of_date: {type: string, format: date}
      responses: {'201': {description: Sealed research snapshot}}
  /quant/research/snapshots/{uid}:
    get:
      summary: Retrieve a sealed research snapshot and its point-in-time feature rows
      x-financegpt-scope: quant:research:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Sealed snapshot and feature matrix}}
  /quant/research/runs:
    post:
      summary: Run a governed feature-quality experiment against a sealed snapshot
      x-financegpt-scope: quant:research:run
      responses: {'201': {description: Reproducible experiment result}}
  /quant/models:
    get:
      summary: List validated deterministic FinanceGPT quantitative models
      x-financegpt-scope: quant:models:read
      responses: {'200': {description: Quantitative model registry and active model cards}}
  /quant/models/{key}:
    get:
      summary: Get one quantitative model card, schema, methodology and validation evidence
      x-financegpt-scope: quant:models:read
      parameters: [{in: path, name: key, required: true, schema: {type: string}}]
      responses: {'200': {description: Quantitative model card}}
  /quant/models/{key}/run:
    post:
      summary: Execute a validated deterministic quantitative model
      x-financegpt-scope: quant:models:run
      parameters: [{in: path, name: key, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input: {type: object, additionalProperties: true}
      responses:
        '201': {description: Versioned model output with reproducibility hashes}
        '422': {description: Invalid model input}
  /quant/model-runs:
    get:
      summary: Read workspace quantitative-model execution history
      x-financegpt-scope: quant:models:read
      parameters: [{in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}]
      responses: {'200': {description: Workspace model execution history without decrypted model inputs}}
  /quant/statistical-models:
    get:
      summary: List FinanceGPT forecasting, econometrics, volatility, factor and statistical-risk models
      x-financegpt-scope: quant:models:read
      responses: {'200': {description: M19 statistical model registry cards}}
  /quant/model-tournaments:
    get:
      summary: List workspace forecast-model tournaments
      x-financegpt-scope: quant:models:read
      parameters: [{in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}]
      responses: {'200': {description: Workspace tournament history}}
    post:
      summary: Run a governed holdout forecast-model tournament
      x-financegpt-scope: quant:models:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [series]
              properties:
                series: {type: array, minItems: 12, maxItems: 5000, items: {type: number}}
                name: {type: string}
                holdout: {type: integer, minimum: 2, maximum: 120}
                forecast_horizon: {type: integer, minimum: 1, maximum: 60}
                metric: {type: string, enum: [mae, rmse, mape]}
                candidate_models: {type: array, minItems: 2, maxItems: 6, items: {type: string}}
      responses:
        '201': {description: Completed tournament with candidate errors and selected forecast}
        '422': {description: Invalid tournament input or no successful candidates}
  /quant/model-tournaments/{uid}:
    get:
      summary: Retrieve one governed forecast-model tournament
      x-financegpt-scope: quant:models:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Tournament result and candidate evaluation metrics}}
  /generative/models:
    get:
      summary: List approved FinanceGPT generative financial models
      x-financegpt-scope: generative:models:read
      responses: {'200': {description: Approved model cards, algorithms, artifact hashes and evaluation evidence}}
  /generative/scenarios:
    post:
      summary: Generate reproducible regime-conditioned financial scenarios
      x-financegpt-scope: generative:inference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [regime]
              properties:
                regime: {type: string, enum: [contraction, neutral, expansion]}
                samples: {type: integer, minimum: 1, maximum: 20, default: 5}
                seed: {type: integer, minimum: 0, maximum: 2147483647, default: 42}
                stress: {type: object, additionalProperties: {type: number}}
      responses:
        '201': {description: Seeded conditional scenario run with reproducibility hashes}
        '409': {description: Approved model or synchronized feature context unavailable}
  /generative/paths:
    post:
      summary: Generate reproducible multi-period synthetic financial stress paths
      x-financegpt-scope: generative:inference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [regime]
              properties:
                regime: {type: string, enum: [contraction, neutral, expansion]}
                samples: {type: integer, minimum: 1, maximum: 20, default: 3}
                horizon: {type: integer, minimum: 1, maximum: 12, default: 6}
                seed: {type: integer, minimum: 0, maximum: 2147483647, default: 42}
                stress: {type: object, additionalProperties: {type: number}}
      responses:
        '201': {description: Seeded multi-period path run with model/version/source hashes}
        '409': {description: Approved time-series model or synchronized feature context unavailable}
  /generative/runs:
    get:
      summary: Read workspace generative-model run history
      x-financegpt-scope: generative:models:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
        - {in: query, name: type, schema: {type: string, enum: [conditional_scenario, time_series_path]}}
      responses: {'200': {description: Workspace-scoped run history with seeds and reproducibility hashes}}
  /generative/runs/{uid}:
    get:
      summary: Retrieve one reproducible generative finance run
      x-financegpt-scope: generative:models:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Generative run result, conditions, seed and hashes}}
  /quant/compute/jobs:
    get:
      summary: List workspace Quant Compute Cloud jobs
      x-financegpt-scope: quant:compute:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
        - {in: query, name: type, schema: {type: string, enum: [backtest, simulation, optimization]}}
      responses: {'200': {description: Durable compute job history without decrypted submission inputs}}
  /quant/compute/jobs/{uid}:
    get:
      summary: Retrieve one Quant Compute Cloud job and completed result
      x-financegpt-scope: quant:compute:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Workspace-scoped job status, hashes and completed result payload}}
  /quant/compute/backtests:
    post:
      summary: Queue a governed historical backtest
      x-financegpt-scope: quant:compute:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input: {type: object, additionalProperties: true}
                service_class: {type: string, nullable: true}
                region: {type: string, nullable: true}
      responses:
        '202': {description: Durable queued backtest job; poll the returned job URL}
        '422': {description: Invalid or oversized compute input}
  /quant/compute/simulations:
    post:
      summary: Queue a seeded Monte Carlo simulation
      x-financegpt-scope: quant:compute:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input: {type: object, additionalProperties: true}
                service_class: {type: string, nullable: true}
                region: {type: string, nullable: true}
      responses:
        '202': {description: Durable queued simulation job; poll the returned job URL}
        '422': {description: Invalid or oversized compute input}
  /quant/compute/optimizations:
    post:
      summary: Queue a bounded parameter-grid optimization over an approved FinanceGPT model
      x-financegpt-scope: quant:compute:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input: {type: object, additionalProperties: true}
                service_class: {type: string, nullable: true}
                region: {type: string, nullable: true}
      responses:
        '202': {description: Durable queued optimization job; poll the returned job URL}
        '422': {description: Invalid model, objective or parameter grid}
  /quant/compute/jobs/{uid}/cancel:
    post:
      summary: Cancel a queued Quant Compute Cloud job
      x-financegpt-scope: quant:compute:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses:
        '200': {description: Queued job cancelled}
        '409': {description: Running or terminal jobs cannot be cancelled}
  /lqm/platform:
    get:
      summary: Read the governed LQM Builder platform foundation
      description: Returns the canonical LQM terminology, reused FinanceGPT infrastructure, quantitative-only execution boundaries, required schema readiness and workspace-level foundation counts. LQMs are quantitative/generative modules; language generation and Financial Actions authority remain outside this contract.
      x-financegpt-scope: lqm:build:read
      responses:
        '200': {description: LQM platform foundation contract and readiness}
        '403': {description: 'Credential does not have lqm:build:read'}

  /lqm/developer-manifest:
    get:
      summary: Read the machine-readable LQM developer platform contract
      description: Returns the canonical quantitative-only LQM definition, lifecycle, least-privilege capability profiles, API endpoint catalog, evidence contract and non-negotiable execution boundaries. Public model-hub publishing is reported separately and is not implied by internal promotion.
      x-financegpt-scope: lqm:build:read
      responses:
        '200': {description: LQM developer platform manifest}
        '403': {description: 'Credential does not have lqm:build:read'}
  /lqm/models/{uid}/developer-manifest:
    get:
      summary: Read model-specific LQM developer readiness
      description: Returns the exact workspace model lifecycle state and whether training, evaluation, Evidence Packet issuance, model-hub publishing, promotion and QLM composition are currently eligible. Gated operations include reason codes and never bypass their underlying governance checks.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Model-specific LQM developer manifest}
        '404': {description: LQM not found in this workspace}

  /lqm/models:
    get:
      summary: List governed workspace LQM registry records
      x-financegpt-scope: lqm:build:read
      responses:
        '200': {description: Workspace LQM registry records}
    post:
      summary: Register a quantitative LQM before training
      description: Creates the canonical model identity in the existing FinanceGPT ML registry and attaches an LQM profile. This does not start training.
      x-financegpt-scope: lqm:build:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, task_family]
              properties:
                name: {type: string, maxLength: 191}
                task_family: {type: string, enum: [forecasting, valuation, risk, simulation, optimization, scenario_generation]}
                intended_use: {type: string, nullable: true, maxLength: 255}
                license: {type: string, nullable: true, maxLength: 96}
      responses:
        '201': {description: LQM registered; training remains gated}
        '422': {description: Invalid LQM registration}
  /lqm/models/{uid}:
    get:
      summary: Read an LQM registry record and its sealed training specifications
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: LQM registry record}
        '404': {description: LQM not found in this workspace}
  /lqm/datasets/{dataset}/contracts:
    post:
      summary: Seal a numeric LQM training-data contract
      description: Validates the quantitative-only input boundary and seals source, feature-schema and lineage hashes without copying raw payload data into the lineage record.
      x-financegpt-scope: lqm:build:write
      parameters: [{in: path, name: dataset, required: true, schema: {type: integer}}]
      responses:
        '201': {description: Immutable LQM dataset contract}
        '409': {description: Dataset is ineligible, expired, changed after sealing, or violates the LQM input boundary}
  /lqm/models/{uid}/training-specs:
    get:
      summary: List immutable pre-training specifications for an LQM
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Sealed LQM training specifications}
    post:
      summary: Seal a reproducible VAE-GAN training specification
      description: Fixes dataset contract, random seed, split, VAE-GAN architecture and bounded training configuration before compute execution. It does not itself create or run a training job.
      x-financegpt-scope: lqm:build:write
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dataset_contract_uid]
              properties:
                dataset_contract_uid: {type: string}
                random_seed: {type: integer, minimum: 0, maximum: 2147483647}
                training_config: {type: object, additionalProperties: true}
      responses:
        '201': {description: Immutable pre-training lineage specification}
        '409': {description: Dataset contract or training configuration rejected}
  /lqm/models/{uid}/training-runs:
    get:
      summary: List governed VAE-GAN training runs for an LQM
      description: Returns queued, running, failed and completed training runs. Completed runs include exact parameter count, checkpoint SHA-256, training metrics and runtime evidence, but remain non-promotable until the required LQM evaluation suite passes.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: LQM training-run records}
    post:
      summary: Queue a sealed LQM VAE-GAN training run
      description: Binds an immutable training specification to the existing FinanceGPT ML training-job control plane and private numeric runtime. Successful training seals a model version but never activates or promotes it.
      x-financegpt-scope: lqm:build:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [training_spec_uid]
              properties:
                training_spec_uid: {type: string}
      responses:
        '202': {description: Governed VAE-GAN training queued}
        '409': {description: Runtime unavailable, specification ineligible, lineage mismatch or duplicate failed lineage}
  /lqm/training-runs/{runUid}:
    get:
      summary: Read a governed LQM training run and checkpoint evidence
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: runUid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Training state, architecture, exact parameter count, checkpoint SHA-256, metrics and runtime evidence}
        '404': {description: LQM training run not found in this workspace}

  /lqm/models/{uid}/evaluations:
    get:
      summary: List LQM checkpoint evaluations
      description: Returns versioned statistical-fidelity, temporal, cross-series, tail, diversity and robustness gate evidence for this LQM.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Governed LQM evaluation records}
  /lqm/models/{uid}/evaluate:
    post:
      summary: Evaluate a sealed LQM checkpoint
      description: Queues the versioned statistical-fidelity and financial robustness suite against an exact checkpoint SHA-256 and unchanged dataset contract. Passing does not activate, publish or promote the checkpoint.
      x-financegpt-scope: lqm:build:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [training_run_uid]
              properties:
                training_run_uid: {type: string}
      responses:
        '202': {description: LQM evaluation queued}
        '409': {description: Checkpoint, dataset lineage or evaluation runtime is ineligible}
  /lqm/evaluation-runs/{evaluationUid}:
    get:
      summary: Read a governed LQM evaluation run
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: evaluationUid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Evaluation state, required gate results, sealed evaluation hash, baseline comparison and runtime evidence}
        '404': {description: LQM evaluation run not found in this workspace}

  /lqm/models/{uid}/evidence-schema:
    get:
      summary: Read the versioned LQM Evidence Packet schema
      description: Returns the immutable JSON contract and schema SHA-256 that a QLM language runtime may consume as typed quantitative evidence. It exposes no LQM latent state.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Versioned LQM Evidence Packet JSON schema and seal}
        '404': {description: LQM not found in this workspace}
  /lqm/models/{uid}/evidence-packets:
    get:
      summary: List sealed Evidence Packets for an LQM
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Workspace-scoped immutable Evidence Packet history}
    post:
      summary: Generate an Evidence Packet from a passed LQM checkpoint
      description: Runs bounded deterministic-seed inference against the exact evaluated checkpoint, records the existing ML inference run, seals typed quantitative output and appends a hash-linked model evidence ledger event. This does not activate, publish or promote the checkpoint.
      x-financegpt-scope: lqm:build:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [evaluation_uid]
              properties:
                evaluation_uid: {type: string}
                seed: {type: integer, minimum: 0, maximum: 2147483647}
                sample_count: {type: integer, minimum: 1, maximum: 50, default: 5}
      responses:
        '201': {description: Immutable LQM Evidence Packet issued}
        '409': {description: Evaluation, checkpoint, lineage or private runtime is ineligible}
  /lqm/evidence-packets/{packetUid}:
    get:
      summary: Read one immutable LQM Evidence Packet
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: packetUid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Typed packet, provenance, quantitative result and SHA-256 seals}
        '404': {description: Evidence Packet not found in this workspace}
  /lqm/evidence-packets/{packetUid}/verify:
    post:
      summary: Independently verify an LQM Evidence Packet and model evidence chain
      description: Recomputes the schema hash, packet hash, output hash and hash-linked per-model evidence ledger and re-attests the checkpoint and evaluation hashes. Verification never grants model promotion or Financial Actions authority.
      x-financegpt-scope: lqm:build:run
      parameters: [{in: path, name: packetUid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Evidence Packet verification passed}
        '409': {description: One or more packet or ledger integrity checks failed}

  /infrastructure/posture:
    get:
      summary: Read workspace institutional compute and licensing posture
      x-financegpt-scope: infrastructure:read
      responses: {'200': {description: Service class, region policy, data grants and deployment-truth claims}}
  /infrastructure/service-classes:
    get:
      summary: List FinanceGPT compute service classes
      x-financegpt-scope: infrastructure:read
      responses: {'200': {description: Compute service classes and service-target metadata}}
  /infrastructure/regions:
    get:
      summary: List configured compute regions and explicit deployment state
      x-financegpt-scope: infrastructure:read
      responses: {'200': {description: Provisioned and planned region metadata}}
  /infrastructure/usage:
    get:
      summary: Read 30-day institutional compute telemetry
      x-financegpt-scope: infrastructure:read
      responses: {'200': {description: Queue, compute, unit and estimated-cost telemetry}}
  /infrastructure/data-entitlements:
    get:
      summary: Read workspace contractual data-entitlement overlays
      x-financegpt-scope: infrastructure:read
      responses: {'200': {description: Dataset use, region and jurisdiction grants}}
  /infrastructure/lineage-exports:
    post:
      summary: Create a sealed FinanceGPT lineage manifest
      x-financegpt-scope: infrastructure:lineage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [scope_type]
              properties:
                scope_type: {type: string, enum: [workspace, compute_job, quant_model_run, ml_inference]}
                scope_id: {type: string, nullable: true}
      responses:
        '201': {description: SHA-256 sealed lineage export created}
        '422': {description: Unsupported scope or unknown governed record}
  /infrastructure/lineage-exports/{uid}:
    get:
      summary: Retrieve a sealed lineage manifest
      x-financegpt-scope: infrastructure:lineage
      parameters: [{in: path, name: uid, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Lineage manifest without secrets or raw ML training data}}
  /marketplace/listings:
    get:
      summary: Discover verified marketplace APIs, models, datasets and FinanceGPT-native workflows
      x-financegpt-scope: marketplace:read
      parameters:
        - {in: query, name: category, schema: {type: string}}
      responses:
        '200': {description: Platform-reviewed publisher listings and active commercial offers}
  /marketplace/{slug}/invoke:
    post:
      summary: Invoke an actively subscribed verified marketplace listing, including a governed native workflow
      x-financegpt-scope: marketplace:invoke
      parameters:
        - {in: path, name: slug, required: true, schema: {type: string}}
      requestBody:
        required: false
        content:
          application/json:
            schema: {type: object, additionalProperties: true}
      responses:
        '200': {description: Publisher JSON response wrapped by the FinanceGPT gateway}
        '403': {description: Active marketplace subscription required}
        '429': {description: FinanceGPT or marketplace subscription request limit exceeded}
        '502': {description: Publisher upstream failed security or invocation checks}
  /companies:
    get:
      summary: List company-finance workspaces
      x-financegpt-scope: financial:analysis:read
      responses: {'200': {description: Companies with source and coverage metadata}}
  /companies/{company}:
    get:
      summary: Read company finance profile and data coverage
      x-financegpt-scope: financial:analysis:read
      parameters: [{in: path, name: company, required: true, schema: {type: integer}}]
      responses: {'200': {description: Company finance profile}}
  /companies/{company}/financials:
    get:
      summary: Read normalized financial periods with source provenance
      x-financegpt-scope: financial:analysis:read
      parameters: [{in: path, name: company, required: true, schema: {type: integer}}]
      responses: {'200': {description: Financial periods; unavailable values remain null}}
  /companies/{company}/ratios:
    get:
      summary: Read deterministic financial ratios
      x-financegpt-scope: financial:analysis:read
      parameters: [{in: path, name: company, required: true, schema: {type: integer}}]
      responses: {'200': {description: Liquidity, leverage, profitability, coverage and cash-flow ratios}}
  /companies/{company}/analysis:
    get:
      summary: Read company analysis, financial resilience, DCF and linked forecast
      x-financegpt-scope: financial:analysis:read
      parameters: [{in: path, name: company, required: true, schema: {type: integer}}]
      responses: {'200': {description: Deterministic analysis with methodology disclosures}}
  /companies/{company}/valuations:
    post:
      summary: Run free-cash-flow DCF valuation
      x-financegpt-scope: financial:analysis:run
      parameters: [{in: path, name: company, required: true, schema: {type: integer}}]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                wacc: {type: number}
                terminal_growth: {type: number}
      responses:
        '201': {description: DCF result with explicit assumptions and sensitivity evidence}
        '422': {description: Insufficient free-cash-flow evidence or invalid assumptions}
  /companies/{company}/scenarios:
    post:
      summary: Run deterministic company revenue and expense scenarios
      x-financegpt-scope: financial:analysis:run
      parameters: [{in: path, name: company, required: true, schema: {type: integer}}]
      responses: {'201': {description: Scenario comparison against the latest recorded period}}
  /knowledge/bases:
    get:
      summary: List accessible FinanceGPT Knowledge Intelligence bases
      security: [{FinanceApiKey: ['knowledge:read']}]
      responses:
        '200': {description: Knowledge base catalogue}
  /knowledge/documents:
    get:
      summary: List workspace-visible ready knowledge documents
      security: [{FinanceApiKey: ['knowledge:read']}]
      responses:
        '200': {description: Knowledge documents}
    post:
      summary: Ingest a document into a workspace-visible knowledge base
      description: Stores the raw file privately and extracts deterministic source lineage. Image-only PDFs require a separately configured OCR-capable ingestion path.
      security: [{FinanceApiKey: ['knowledge:write']}]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [base_uid, file]
              properties:
                base_uid: {type: string, format: uuid}
                file: {type: string, format: binary}
                title: {type: string}
                data_classification: {type: string, enum: [public, internal, confidential, restricted]}
      responses:
        '201': {description: Document ingested}
        '422': {description: File stored but extraction failed or was unsupported}
  /knowledge/documents/{uid}:
    get:
      summary: Read knowledge document metadata and lineage counts
      security: [{FinanceApiKey: ['knowledge:read']}]
      parameters:
        - {name: uid, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Knowledge document metadata}
  /knowledge/query:
    post:
      summary: Ask FinanceGPT against permission-scoped Knowledge Intelligence evidence
      description: Retrieval fails closed when no accessible evidence matches. Managed AI consumes FinanceGPT AI Credits under AI3 enforcement; BYOK remains customer-provider-direct under AI6/AI7 policy.
      security: [{FinanceApiKey: ['knowledge:query']}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [question]
              properties:
                question: {type: string}
                base_uid: {type: string, format: uuid}
                document_uid: {type: string, format: uuid}
                model_selection: {type: string, example: auto_native, description: Universal NI6 model selection key; Auto — FinanceGPT Native is the default}
                financegpt_model: {type: string, example: financegpt-research, description: Legacy FinanceGPT managed-model field retained for compatibility}
      responses:
        '200': {description: Source-grounded answer with citations and AI billing mode}
        '409': {description: AI route unavailable or credit/provider policy requires user action}

  /integrations:
    get:
      summary: Read workspace Integration Hub connections and secret-free tool definitions
      x-financegpt-scope: integrations:read
      responses:
        '200': {description: Workspace integration catalogue, status, capabilities, access posture and discovered MCP tools}
  /data/tables:
    get:
      summary: Read governed FinanceGPT Data Studio tables
      x-financegpt-scope: data:tables:read
      responses:
        '200': {description: Workspace Data Studio tables with source lineage, schemas and classifications}
  /data/tables/{uid}:
    get:
      summary: Read one governed Data Studio table and bounded preview
      x-financegpt-scope: data:tables:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Table schema, source SHA-256 and bounded row preview}
  /data/tables/{uid}/ask:
    post:
      summary: Plan and execute a governed natural-language Data Studio operation
      description: Uses the NI6 Universal Model Switching contract for the language-planning stage, then executes only allow-listed deterministic table operations.
      x-financegpt-scope: data:tables:run
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt: {type: string, maxLength: 5000}
                model_selection: {type: string, example: auto_native}
                financegpt_model: {type: string, description: Legacy compatibility field}
      responses:
        '201': {description: Deterministic Data Studio operation result, model-selection evidence and actual settled AI Credits}
        '422': {description: Language planning or bounded operation validation failed}
  /data/tables/{uid}/operations:
    post:
      summary: Execute an allow-listed deterministic Data Studio operation pipeline
      x-financegpt-scope: data:tables:run
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [operations]
              properties:
                operations:
                  type: array
                  maxItems: 20
                  items: {type: object}
      responses:
        '200': {description: Deterministic operation evidence with specification/result hashes and bounded preview}
        '422': {description: Invalid or unsupported operation specification}
  /actions/authorities:
    get:
      summary: List active and historical action-scoped authorities for the workspace
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Delegated user or role authority scopes with limits, validity and evidence hashes}
  /actions/counterparties:
    get:
      summary: List governed Financial Action counterparties and current settlement-destination status
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Counterparty identity, risk and versioned settlement-destination verification evidence}
  /actions/policies:
    get:
      summary: List scoped Financial Actions policies and conditional rules
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Policy scope, authority requirement, risk floor, approvals and rule evidence}
  /actions/risk-rules:
    get:
      summary: List active and historical dynamic Financial Action risk rules
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Workspace and policy-scoped risk rules with conditions, effects, priority and lifecycle evidence}
  /actions/approval-graphs:
    get:
      summary: List governed Financial Action approval graphs
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Approval graphs and ordered quorum nodes with role/user constraints, expiry and material-change behavior}
  /actions/execution-profiles:
    get:
      summary: List Payments & Treasury execution profiles and engaged kill switches
      description: Profiles expose governed action, account, currency, counterparty, monetary-limit, operating-mode, health and credential-boundary metadata. Secret credentials are never returned.
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Versioned execution profiles plus currently engaged workspace or connector kill switches}
  /actions/execution-instructions:
    get:
      summary: List governed Payments & Treasury execution instructions
      x-financegpt-scope: actions:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
      responses:
        '200': {description: Secret-free dispatch instruction evidence with idempotency, payload, credential-boundary and provider outcome hashes}
  /actions/reconciliation:
    get:
      summary: List Financial Action settlement and reconciliation status
      description: Returns only governed action and settlement evidence. Provider submission is not treated as completion; successful actions require conservative settlement matching and a final reconciliation evidence seal.
      x-financegpt-scope: actions:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
      responses:
        '200': {description: Reconciliation state, matched and outstanding integer minor-unit amounts, open exception counts and final evidence seals}
  /actions/reconciliation-exceptions:
    get:
      summary: List Financial Action reconciliation exceptions
      x-financegpt-scope: actions:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
      responses:
        '200': {description: Amount, currency, duplicate, missing-settlement, return, reversal, partial-settlement and other governed exception evidence}
  /actions/reconciliation-exceptions/{uid}/resolve:
    post:
      summary: Resolve a Financial Action reconciliation exception with retained evidence
      description: Resolution records the investigation outcome and actor without deleting or rewriting the original exception evidence.
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [resolution]
              properties:
                resolution: {type: string, minLength: 8, maxLength: 255}
      responses:
        '200': {description: Exception resolved with updated evidence hash}
        '422': {description: Exception is not open or the resolution evidence is invalid}
  /actions/intents:
    get:
      summary: List governed Financial Action envelopes for the active workspace
      x-financegpt-scope: actions:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
      responses:
        '200': {description: Financial Action envelopes with control state, risk, checkpoints and reconciliation status}
    post:
      summary: Create a governed Financial Action envelope
      description: Creation records intent, authoritative monetary provenance, policy screening and risk evidence. It does not move money.
      x-financegpt-scope: actions:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [connector_id, currency, amount, idempotency_key]
              properties:
                connector_id: {type: integer}
                counterparty_id: {type: integer}
                action_key: {type: string, example: vendor_payment}
                action_type: {type: string, enum: [payment, collection], description: Legacy-compatible alias when action_key is omitted.}
                currency: {type: string, minLength: 3, maxLength: 3}
                amount: {type: number, exclusiveMinimum: 0}
                purpose: {type: string, maxLength: 255}
                calculation_source: {type: string, enum: [deterministic_calculation, system_of_record, approved_invoice, contract_schedule, market_quote, human_entered_verified]}
                calculation_reference: {type: string, maxLength: 191}
                execution_mode: {type: string, enum: [observe, propose, sandbox, approval_gated_live, policy_controlled_live, autonomous_routine]}
                external_reference: {type: string, maxLength: 191}
                idempotency_key: {type: string, maxLength: 128}
      responses:
        '201': {description: Financial Action envelope created with ten control checkpoints and T1-T4 risk evidence}
        '422': {description: Invalid action, monetary provenance, connector, policy or control input}
  /actions/intents/{uid}:
    get:
      summary: Read one Financial Action envelope and current control-plane state
      x-financegpt-scope: actions:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Action envelope, checkpoints, risk, scoped authorization and reconciliation state}
  /actions/intents/{uid}/evidence:
    get:
      summary: Read structured Financial Action control and evidence lineage
      x-financegpt-scope: actions:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Checkpoints, state transitions, risk assessments, authorizations, action events and reconciliation evidence}
  /actions/intents/{uid}/approval-run:
    get:
      summary: Read the current Financial Action approval run and quorum progress
      x-financegpt-scope: actions:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Current approval graph run, slot assignments, stage progress, expiry and material-scope evidence}
        '404': {description: No current approval run exists for the action}
  /actions/intents/{uid}/submit:
    post:
      summary: Submit a Financial Action for governed human approval
      x-financegpt-scope: actions:create
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [approver_ids]
              properties:
                approver_ids: {type: array, minItems: 1, maxItems: 12, items: {type: integer}}
      responses:
        '200': {description: Financial Action moved to the human approval gate after control revalidation}
        '422': {description: Required pre-approval control, policy or segregation-of-duties condition failed}
  /actions/intents/{uid}/execute:
    post:
      summary: Execute an authorized Financial Action through its separate execution authority
      description: Execution revalidates current policy and authorization scope. Governed payment, treasury, credit, collection and corporate-action keys additionally require an active execution profile whose action/account/currency/counterparty limits, operating mode, credential boundary, health and kill-switch state pass immediately before dispatch. T3 and T4 actions require explicit human authorization; proposal and observe modes cannot execute. Investment action keys are deliberately rejected here and execute only through the governed investment-order bridge.
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Execution evidence and resulting reconciliation state}
        '422': {description: Authorization, policy, execution mode or connector preflight failed}
  /actions/intents/{uid}/reconcile:
    post:
      summary: Reconcile an executed Financial Action against settlement evidence
      x-financegpt-scope: actions:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Conservative settlement reconciliation result; an action is complete only when matched}


  /actions/investment-execution:
    get:
      summary: List investment order batches converged into governed Financial Actions
      description: Returns canonical Action Envelope linkage, material order hashes, pre-trade control state and trade-confirmation evidence while broker credentials remain in the investment execution runtime.
      x-financegpt-scope: investment:read
      responses:
        '200': {description: Linked investment batches plus eligible legacy order-batch candidates}
    post:
      summary: Adopt an investment order batch into the Financial Actions control plane
      description: Creates one canonical Action Envelope for an existing governed investment order batch. This does not execute the order batch and does not copy broker credentials into AI or Financial Actions context.
      x-financegpt-scope: investment:execute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [batch_uid, connector_id, action_key, currency, amount, purpose, calculation_source, calculation_reference, execution_mode]
              properties:
                batch_uid: {type: string, maxLength: 96}
                connector_id: {type: integer, description: Canonical Financial Actions governance connector; broker credentials remain on the existing investment connector.}
                action_key: {type: string, enum: [buy_sell_securities, portfolio_rebalance_trade, tax_harvest_trade, fx_trading]}
                currency: {type: string, minLength: 3, maxLength: 3}
                amount: {type: number, exclusiveMinimum: 0}
                purpose: {type: string, maxLength: 255}
                calculation_source: {type: string, enum: [deterministic_calculation, system_of_record, market_quote]}
                calculation_reference: {type: string, maxLength: 191}
                execution_mode: {type: string, enum: [sandbox, approval_gated_live]}
                source_evidence: {type: object}
      responses:
        '201': {description: Investment batch linked to a canonical Action Envelope with material-scope evidence}
        '422': {description: Batch, amount, connector, execution mode or source evidence failed convergence validation}
  /actions/investment-execution/{uid}:
    get:
      summary: Read one governed investment execution convergence record
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Action linkage, latest pre-trade controls, trade confirmations and bridge events}
  /actions/investment-execution/{uid}/refresh:
    post:
      summary: Refresh material investment-order scope and invalidate stale approval when needed
      description: Re-hashes the authoritative batch and order intents. Any material change resets required pre-trade evidence and invalidates current approval or execution authorization.
      x-financegpt-scope: investment:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Refreshed material scope and control evidence}
        '422': {description: Investment order batch could not be refreshed safely}
  /actions/investment-execution/{uid}/checks:
    post:
      summary: Record a versioned investment pre-trade control result
      description: Required mandate, deterministic sizing, exposure, concentration, buying-power, instrument, venue, broker, custody, legacy integrity and order-idempotency evidence is bound into Financial Action approval scope.
      x-financegpt-scope: investment:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [check_key, status, source_type]
              properties:
                check_key: {type: string}
                status: {type: string, enum: [passed, failed, pending, not_applicable]}
                source_type: {type: string, maxLength: 48}
                source_reference: {type: string, maxLength: 191}
                source_hash: {type: string, minLength: 64, maxLength: 64}
                metrics: {type: object}
                metadata: {type: object}
      responses:
        '200': {description: Append-only pre-trade control version recorded; stale approval is invalidated when applicable}
        '422': {description: Invalid control status or required source evidence}
  /actions/investment-execution/{uid}/confirmations:
    post:
      summary: Record broker trade-confirmation evidence without treating it as settlement
      x-financegpt-scope: investment:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '201': {description: Trade confirmation evidence recorded; Financial Action remains subject to custody reconciliation}
  /actions/investment-execution/{uid}/custody:
    post:
      summary: Record independent custody settlement evidence and run canonical reconciliation
      description: Custody observations flow into the Financial Actions reconciliation engine. Trade confirmation alone does not close the action.
      x-financegpt-scope: investment:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Custody observation evaluated through reconciliation and exception intelligence}
        '422': {description: Invalid or insufficient custody settlement evidence}

  /actions/credit-corporate:
    get:
      summary: List governed credit, collections and corporate-action links
      description: Returns Action Envelope links to sealed obligations, accepted arrangements or corporate instructions plus the latest domain-control evidence. Source records remain distinct from execution instructions.
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Governed domain action links and control status}
    post:
      summary: Create a governed credit, collection or corporate action from a sealed source record
      description: Creates a canonical Action Envelope only after amount, currency, counterparty and source-record scope are validated. Supported execution modes are sandbox and approval-gated live; this endpoint does not execute the action.
      x-financegpt-scope: actions:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action_key, source_uid, connector_id, counterparty_id, currency, amount, purpose, calculation_source, calculation_reference, execution_mode, idempotency_key]
              properties:
                action_key: {type: string, enum: [loan_repayment, line_of_credit_draw, line_of_credit_repayment, loan_origination_disbursement, debt_collection_settlement, repayment_arrangement_collection, escrow_release, private_markets_capital_call, private_markets_distribution, shareholder_dividend_distribution]}
                source_uid: {type: string, format: uuid}
                arrangement_uid: {type: string, format: uuid}
                connector_id: {type: integer}
                counterparty_id: {type: integer}
                currency: {type: string, minLength: 3, maxLength: 3}
                amount: {type: number, exclusiveMinimum: 0}
                purpose: {type: string, maxLength: 255}
                external_reference: {type: string, maxLength: 191}
                calculation_source: {type: string, maxLength: 48}
                calculation_reference: {type: string, maxLength: 191}
                execution_mode: {type: string, enum: [sandbox, approval_gated_live]}
                idempotency_key: {type: string, maxLength: 128}
      responses:
        '201': {description: Source-bound Financial Action created; required domain controls must pass before approval}
        '422': {description: Source, amount, counterparty, connector or execution-mode validation failed}
  /actions/credit-corporate/obligations:
    get:
      summary: List governed credit and collection obligations
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Obligation records with sealed source evidence and integer-minor-unit economic scope}
    post:
      summary: Register a governed obligation source record
      x-financegpt-scope: actions:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [counterparty_id, obligation_type, source_reference, source_hash, currency, status]
              properties:
                counterparty_id: {type: integer}
                obligation_type: {type: string, maxLength: 48}
                source_system: {type: string, maxLength: 64}
                source_reference: {type: string, maxLength: 191}
                source_hash: {type: string, minLength: 64, maxLength: 64, description: SHA-256 of authoritative source evidence.}
                facility_reference: {type: string, maxLength: 191}
                currency: {type: string, minLength: 3, maxLength: 3}
                original_amount: {type: number, minimum: 0}
                outstanding_amount: {type: number, minimum: 0}
                available_amount: {type: number, minimum: 0}
                status: {type: string}
                due_date: {type: string, format: date}
      responses:
        '201': {description: Governed obligation registered without granting execution authority}
        '422': {description: Invalid or conflicting source evidence}
  /actions/credit-corporate/arrangements:
    get:
      summary: List accepted settlement and repayment arrangements
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Version-evidenced arrangement records}
    post:
      summary: Register an accepted settlement or repayment arrangement
      x-financegpt-scope: actions:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [obligation_uid, arrangement_type, source_reference, source_hash, terms_hash, currency, agreed_amount, status]
              properties:
                obligation_uid: {type: string, format: uuid}
                arrangement_type: {type: string, maxLength: 48}
                source_reference: {type: string, maxLength: 191}
                source_hash: {type: string, minLength: 64, maxLength: 64}
                terms_hash: {type: string, minLength: 64, maxLength: 64, description: SHA-256 of accepted economic terms.}
                currency: {type: string, minLength: 3, maxLength: 3}
                agreed_amount: {type: number, exclusiveMinimum: 0}
                discount_amount: {type: number, minimum: 0}
                installment_count: {type: integer, minimum: 1}
                starts_on: {type: string, format: date}
                expires_on: {type: string, format: date}
                status: {type: string}
      responses:
        '201': {description: Accepted arrangement registered and bound to its obligation}
        '422': {description: Invalid arrangement or evidence hash}
  /actions/credit-corporate/instructions:
    get:
      summary: List governed corporate and treasury instructions
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Corporate instruction records with governing source evidence and authorized monetary scope}
    post:
      summary: Register a governed corporate instruction
      x-financegpt-scope: actions:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [counterparty_id, instruction_type, source_reference, source_hash, currency, authorized_amount, status, condition_hash]
              properties:
                counterparty_id: {type: integer}
                instruction_type: {type: string, maxLength: 64}
                source_system: {type: string, maxLength: 64}
                source_reference: {type: string, maxLength: 191}
                source_hash: {type: string, minLength: 64, maxLength: 64}
                governing_document_reference: {type: string, maxLength: 191}
                currency: {type: string, minLength: 3, maxLength: 3}
                authorized_amount: {type: number, exclusiveMinimum: 0}
                status: {type: string}
                effective_at: {type: string, format: date-time}
                expires_at: {type: string, format: date-time}
                condition_hash: {type: string, minLength: 64, maxLength: 64}
                beneficiary_hash: {type: string, minLength: 64, maxLength: 64}
      responses:
        '201': {description: Corporate instruction registered without granting execution authority}
        '422': {description: Invalid instruction or evidence scope}
  /actions/credit-corporate/{uid}/refresh:
    post:
      summary: Refresh source-record scope and invalidate stale approval when material evidence changed
      description: Recomputes the authoritative source and terms hashes. Material changes reset domain controls and change the Action Envelope control-scope hash before any further approval or execution.
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Source scope refreshed and stale controls or approval invalidated when required}
        '422': {description: Source record cannot be safely refreshed}
  /actions/credit-corporate/{uid}/checks:
    post:
      summary: Record a versioned credit, collection or corporate-action domain control
      description: Required source, amount, counterparty, facility, accepted-arrangement, escrow, entitlement, tax or corporate-authorization controls are append-only and become part of approval scope. All required checks must pass before approval.
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [check_key, status, source_type]
              properties:
                check_key: {type: string, maxLength: 64}
                status: {type: string, enum: [passed, failed, pending]}
                source_type: {type: string, maxLength: 48}
                source_reference: {type: string, maxLength: 191}
                source_hash: {type: string, minLength: 64, maxLength: 64}
                metrics: {type: object}
                metadata: {type: object}
      responses:
        '200': {description: Versioned domain-control evidence recorded; material scope changes invalidate prior approval}
        '422': {description: Unknown control, invalid evidence or unsupported status}

  /client-intelligence/calls:
    get:
      summary: Read governed Client Intelligence conversation records
      x-financegpt-scope: client:intelligence:read
      responses:
        '200': {description: Workspace calls and meetings with consent, lifecycle and evidence status}
  /client-intelligence/calls/{uid}:
    get:
      summary: Read one Client Intelligence conversation with transcript and review evidence
      x-financegpt-scope: client:intelligence:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Conversation, transcript segments, analyses, coaching, review flags and action proposals}
  /client-intelligence/calls/{uid}/transcript:
    post:
      summary: Add a governed transcript version to a Client Intelligence conversation
      x-financegpt-scope: client:intelligence:write
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [transcript]
              properties:
                transcript: {type: string}
                source: {type: string, enum: [manual, uploaded, provider_import]}
                language: {type: string, example: en}
      responses:
        '201': {description: Versioned transcript stored with SHA-256 lineage and parsed evidence segments}
  /client-intelligence/calls/{uid}/transcribe-recording:
    post:
      summary: Transcribe the stored Client Intelligence recording with FinanceGPT Native Speech
      description: Requires a stored recording plus captured consent or an approved not-required policy decision. Processing uses the governed local FinanceGPT Native Speech runtime, has no cloud fallback, and settles 0 FinanceGPT AI Credits.
      x-financegpt-scope: client:intelligence:run
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                language: {type: string, example: en}
      responses:
        '201': {description: Native transcript version stored with SHA-256, runtime and diarization evidence}
        '409': {description: Consent, recording integrity or Native Speech readiness prevents transcription}
  /client-intelligence/calls/{uid}/analyse:
    post:
      summary: Run governed FinanceGPT post-call analysis through Hybrid AI routing
      description: Managed AI consumes FinanceGPT AI Credits under the active metering policy; BYOK remains customer-provider-direct. Generated compliance flags are human-review aids and are not legal determinations.
      x-financegpt-scope: client:intelligence:run
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                model_selection: {type: string, example: auto_native}
                financegpt_model: {type: string, example: financegpt-intelligence, description: Legacy compatibility field}
      responses:
        '201': {description: Evidence-backed summary, topics, coaching, action proposals, review flags and AI runtime evidence}
        '409': {description: Hybrid AI route, consent or FinanceGPT AI Credit policy prevents analysis}
  /ai/governance:
    get:
      summary: Read AI quality and governance posture for the active workspace
      x-financegpt-scope: ai:governance:read
      responses:
        '200': {description: Aggregate feedback, evaluation, evidence-hold and assurance posture without raw prompts or provider secrets}
  /ai/evaluations:
    get:
      summary: Read recent governed AI ground-truth evaluation runs
      x-financegpt-scope: ai:governance:read
      responses:
        '200': {description: Evaluation run scores, runtime evidence, credit usage and SHA-256 seals}
  /ai/feedback:
    post:
      summary: Submit a quality signal for an existing FinanceGPT generated output
      x-financegpt-scope: ai:governance:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source_type, source_uid, sentiment]
              properties:
                source_type: {type: string, enum: [copilot_message, knowledge_query, agent_run, client_analysis]}
                source_uid: {type: string}
                sentiment: {type: string, enum: [up, down, flag]}
                reason_code: {type: string}
                comment: {type: string, maxLength: 4000}
      responses:
        '201': {description: Feedback recorded}
  /actions/agentic:
    get:
      summary: Read machine financial identities, delegations, signed actions and kill switches
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Machine Authority operational evidence for the active workspace}
  /actions/agentic/identities:
    post:
      summary: Register a versioned machine financial identity
      description: Stores only an Ed25519 public verification key and non-secret signer reference. Private signing keys remain outside FinanceGPT and AI context.
      x-financegpt-scope: actions:create
      responses:
        '201': {description: Draft machine financial identity and immutable version evidence created}
  /actions/agentic/identities/{uid}/versions:
    post:
      summary: Record a new machine financial-identity version
      x-financegpt-scope: actions:create
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '201': {description: New identity version created; prior delegations are superseded}
  /actions/agentic/identities/{uid}/activate:
    post:
      summary: Activate a machine financial identity after verification
      x-financegpt-scope: actions:create
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Machine identity activated}
  /actions/agentic/identities/{uid}/delegations:
    post:
      summary: Create a bounded machine financial delegation
      description: Delegations specify action, counterparty, connector, currency, execution-mode, T1/T2 risk and per-action/daily/monthly integer-minor-unit budget scopes and require independent approval.
      x-financegpt-scope: actions:create
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '201': {description: Draft delegation created}
  /actions/agentic/delegations/{uid}/approve:
    post:
      summary: Independently approve a machine financial delegation
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Delegation activated after segregation-of-duties approval}
  /actions/agentic/delegations/{uid}/revoke:
    post:
      summary: Revoke a machine delegation and release open reservations
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Delegation revoked}
  /actions/agentic/kill-switches:
    post:
      summary: Engage a workspace, machine-identity or delegation execution kill switch
      x-financegpt-scope: actions:execute
      responses:
        '201': {description: Kill switch engaged and future machine execution fails closed}
  /actions/agentic/kill-switches/{uid}/release:
    post:
      summary: Release a machine financial kill switch
      x-financegpt-scope: actions:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Kill switch released with evidence}
  /actions/agentic/proposals:
    post:
      summary: Submit an Ed25519-signed machine Financial Action proposal
      description: Replay-protected signed proposals may receive bounded T1/T2 delegated authorization only when every delegation, policy, budget, counterparty, connector and dynamic-risk check passes; otherwise the action remains for human review.
      x-financegpt-scope: actions:create
      responses:
        '201': {description: Signed Action Envelope created with delegated-execution eligibility evidence}
        '422': {description: Signature, identity, delegation or action scope failed closed}
  /actions/agentic/{uid}/execute:
    post:
      summary: Execute a machine-delegated Financial Action using a fresh signed execution instruction
      description: Requires a second replay-protected Ed25519 signature, an active agent-delegation authorization, an unexpired budget reservation and T1/T2 dynamic risk. Sandbox remains available under Machine Authority. Human-approved live execution remains approval-gated. Autonomous live execution additionally requires application-only institutional admission, approved premium commercial terms, current multi-domain assessment and FinanceGPT certification, an exact platform-approved restricted autonomy mandate, aggregate institution/mandate budget capacity, current workspace assurance/reconciliation health and no engaged platform suspension. Completion remains reconciliation-gated.
      x-financegpt-scope: actions:autonomous
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Machine action dispatched through the governed execution rail; completion remains reconciliation-gated}
        '422': {description: Machine authority failed closed or execution outcome requires exception handling}
  /actions/autonomy:
    get:
      summary: Read restricted institutional autonomous-operations status
      description: Returns application, assessment, certification, mandate, budget and suspension evidence for the active workspace. Autonomous live access is restricted, application-only and cannot be self-enabled.
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Restricted institutional autonomy status and evidence}
  /actions/autonomy/application:
    post:
      summary: Request institutional assessment for autonomous financial operations
      description: Starts an application only. This does not grant autonomous execution authority and requires named executive, financial authority, risk, security, technical and autonomy owners.
      x-financegpt-scope: actions:create
      responses:
        '201': {description: Institutional application recorded for FinanceGPT review}
        '422': {description: Institutional ownership or admission prerequisites failed}
  /actions/autonomy/assessment-evidence:
    post:
      summary: Submit evidence to an open institutional autonomy assessment
      description: Evidence is classified into required organisation, financial-controls, security, technology, legal/compliance, financial-risk, operational-resilience and governance domains.
      x-financegpt-scope: actions:create
      responses:
        '201': {description: Assessment evidence recorded; no execution authority granted}
  /actions/autonomy/institutional-mandates:
    post:
      summary: Create a draft restricted autonomous financial mandate
      description: Creates an explicit, versioned customer proposal with non-empty machine identity, action, counterparty, connector, currency and execution-mode allowlists plus integer-minor-unit periodic limits. Platform approval is still required.
      x-financegpt-scope: actions:create
      responses:
        '201': {description: Draft institutional autonomous mandate created}
        '422': {description: Scope or monetary limits failed restricted-autonomy controls}
  /actions/autonomy/institutional-mandates/{uid}/submit:
    post:
      summary: Submit a restricted autonomous mandate for FinanceGPT platform approval
      description: Submission does not activate the mandate. FinanceGPT platform approval and current institutional certification remain mandatory.
      x-financegpt-scope: actions:create
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Mandate submitted for platform review}
        '422': {description: Mandate is not eligible for submission}
  /actions/assurance:
    get:
      summary: Read workspace Financial Actions assurance status
      description: Returns the governed suite manifest, category coverage and latest workspace-scoped non-destructive assurance result.
      x-financegpt-scope: actions:read
      responses:
        '200': {description: Assurance suite and latest measured workspace result}
  /actions/assurance/runs:
    post:
      summary: Run the workspace Financial Actions assurance suite
      description: Executes read-only control contracts and current workspace invariant checks. This endpoint does not dispatch production financial actions or expose transaction credentials.
      x-financegpt-scope: actions:execute
      responses:
        '201': {description: Assurance run completed with pass/fail counts and SHA-256 run seal}
        '422': {description: Assurance suite or runtime prerequisite failed closed}
  /acquisition/discovery-catalog:
    get:
      summary: Read the FinanceGPT authoritative public discovery catalog
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Canonical product, solution, pricing-class and operating-boundary discovery manifest}
  /acquisition/metrics:
    get:
      summary: Read measured acquisition and AI-referral evidence for the active commercial context
      x-financegpt-scope: commercial:read
      parameters:
        - {in: query, name: days, schema: {type: integer, minimum: 1, maximum: 365, default: 30}}
      responses:
        '200': {description: Acquisition page, source, CTA and downstream conversion evidence without raw IP or raw third-party AI answers}
  /commercial/catalog:
    get:
      summary: Read the canonical FinanceGPT commercial plan catalog
      description: Returns versioned plan pricing, commercial class and entitlement definitions. Restricted Autonomous Financial Operations remain application-only and are not ordinary subscription entitlements.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Canonical commercial plan catalog}
  /commercial/entitlements:
    get:
      summary: Read the active workspace commercial profile and entitlement matrix
      description: Returns the resolved plan version, source, grandfathering state and explainable capability decisions. Commercial entitlement never substitutes for runtime Financial Actions authority.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Workspace commercial profile and capability matrix}
  /commercial/entitlements/check:
    post:
      summary: Evaluate a FinanceGPT commercial entitlement
      description: Evaluates one capability and optional requested quantity, returning allow/deny, reason code, effective limit and commercial upgrade path. The decision is evidence-recorded and does not change billing.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Explainable commercial entitlement decision}
        '422': {description: Unknown capability or invalid requested quantity}
  /commercial/checkout-intents:
    post:
      summary: Create an authenticated self-service FinanceGPT checkout intent
      description: Creates a continuation-preserving checkout intent for Professional, Team or Business only. Enterprise and Financial Operations remain sales-assisted and Restricted Autonomous Operations remain application-only. This call does not itself activate entitlements or create a financial authority.
      x-financegpt-scope: commercial:write
      responses:
        '201': {description: Checkout intent created}
        '422': {description: Plan, interval, promotion or self-service boundary rejected}
  /commercial/checkout-intents/{uid}:
    get:
      summary: Read a FinanceGPT checkout intent
      description: Returns the authenticated user's checkout intent status, quote and continuation path without exposing payment credentials or provider session URLs.
      x-financegpt-scope: commercial:write
      parameters:
        - {name: uid, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Checkout intent}
        '403': {description: Intent belongs to another user}
  /commercial/billing:
    get:
      summary: Read verified workspace subscription state
      description: Returns the provider-synchronized plan, billing interval, current period end and payment state. Card details and provider secrets are never returned.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Verified self-service billing state}
  /commercial/upgrade-opportunities:
    get:
      summary: List unresolved product-intent commercial upgrade opportunities for the active workspace
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Entitlement-driven upgrade opportunities with no payment credentials or financial authority}
  /commercial/upgrade-recommendations:
    post:
      summary: Resolve the lowest appropriate commercial path for a real product-intent trigger
      x-financegpt-scope: commercial:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [trigger_key]
              properties:
                trigger_key: {type: string}
                requested_value: {type: number, minimum: 0}
                return_to: {type: string, maxLength: 512}
                surface: {type: string, maxLength: 64}
      responses:
        '200': {description: Deterministic recommendation, CTA mode and entitlement reason}
        '422': {description: Unknown trigger or invalid request}
  /commercial/upgrade-opportunities/{uid}/interactions:
    post:
      summary: Record a bounded interaction with one product-led upgrade opportunity
      x-financegpt-scope: commercial:write
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event]
              properties:
                event: {type: string, enum: [exposed, cta_clicked, dismissed]}
                channel: {type: string, enum: [api, in_app, web]}
      responses:
        '200': {description: Recorded interaction and current opportunity status}
        '403': {description: Opportunity belongs to another user or workspace}
  /commercial/value:
    get:
      summary: Read FinanceGPT Value & Outcome Intelligence for the active workspace
      description: Returns measured, derived and explicitly labelled estimated outcomes for the requested period. Estimates are unavailable unless an evidence-backed methodology has been independently approved. Monetary outcomes remain separated by currency without implicit FX conversion.
      x-financegpt-scope: commercial:read
      parameters:
        - {in: query, name: days, schema: {type: integer, minimum: 7, maximum: 365, default: 30}}
      responses:
        '200': {description: Workspace value summary, classifications, source evidence and manifest hash}
  /commercial/value/snapshots:
    get:
      summary: Read sealed FinanceGPT value metric snapshots
      description: Returns workspace-scoped historical metric snapshots plus the latest chained summary seal.
      x-financegpt-scope: commercial:read
      parameters:
        - {in: query, name: limit, schema: {type: integer, minimum: 1, maximum: 500, default: 100}}
      responses:
        '200': {description: Historical measured, derived and governed-estimate snapshots}
  /commercial/value/evidence:
    get:
      summary: Export FinanceGPT value evidence for the active workspace
      description: Returns the current value summary, classification policy and latest seal without presenting estimates as measured savings.
      x-financegpt-scope: commercial:read
      parameters:
        - {in: query, name: days, schema: {type: integer, minimum: 7, maximum: 365, default: 30}}
      responses:
        '200': {description: Value evidence package and latest seal}
  /commercial/usage:
    get:
      summary: Read normalized FinanceGPT commercial usage and allowances
      description: Returns source-distinct AI Credit, API, MCP and agent usage with snapshotted plan allowances and billing state. AI Credits are prepaid service entitlements, not transaction money, and Managed AI credit consumption is never double-billed as metered usage.
      x-financegpt-scope: commercial:read
      parameters:
        - {in: query, name: days, schema: {type: integer, minimum: 1, maximum: 365, default: 30}}
      responses:
        '200': {description: Workspace usage, allowance and billing-period summary}
  /commercial/usage/policy:
    post:
      summary: Configure explicit workspace usage-billing consent
      description: Stores workspace consent and controls for usage billing. Provider invoicing remains independently fail-closed and plan entitlements must explicitly allow overage before any billable overage can be submitted.
      x-financegpt-scope: commercial:write
      responses:
        '200': {description: Updated workspace usage-billing policy}
        '422': {description: Invalid or unsupported billing policy}
  /commercial/usage/budgets:
    post:
      summary: Configure a workspace commercial usage budget
      description: Records commercial usage-budget governance without granting runtime execution authority or replacing existing AI Credit spending controls.
      x-financegpt-scope: commercial:write
      responses:
        '200': {description: Updated commercial usage budget}
        '422': {description: Invalid meter, period, amount or action}
  /commercial/usage/economics:
    get:
      summary: Read workspace usage economics evidence
      description: Returns usage, verified AI Credit and usage cash, provider-cost estimates and operational contribution evidence. Provider cost and contribution are operational estimates rather than statutory revenue-recognition measures; currencies are not implicitly converted.
      x-financegpt-scope: commercial:read
      parameters:
        - {in: query, name: days, schema: {type: integer, minimum: 1, maximum: 365, default: 30}}
      responses:
        '200': {description: Workspace usage economics evidence and source classifications}
  /commercial/financial-operations:
    get:
      summary: Read FinanceGPT Financial Operations commercial status
      description: Returns sales-assisted programme, qualification, approved implementation scope, readiness, active commercial contract and measured customer-success evidence. Commercial state never substitutes for Financial Actions authority, policy, risk, approval, execution or reconciliation controls.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Workspace Financial Operations programme and readiness status}
  /commercial/financial-operations/request:
    post:
      summary: Request FinanceGPT Financial Operations qualification
      description: Opens a sales-assisted Financial Operations pipeline and qualification programme. This is not self-service checkout and creates no live execution authority.
      x-financegpt-scope: commercial:write
      responses:
        '201': {description: Qualification programme requested}
        '422': {description: Invalid request or an active programme already exists}
  /commercial/financial-operations/readiness:
    get:
      summary: Read Financial Operations implementation and live-readiness controls
      description: Returns evidence-backed commercial, authority, counterparty, risk/approval, connector, reconciliation, assurance and operational-readiness controls.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Current Financial Operations readiness evidence}
  /commercial/financial-operations/value:
    get:
      summary: Read measured Financial Operations customer-success evidence
      description: Returns source-backed action, approval, exception and reconciliation outcomes with monetary values separated by currency and no implicit FX conversion.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Latest Financial Operations customer-success snapshot}
  /commercial/financial-operations/snapshot:
    post:
      summary: Capture a Financial Operations customer-success snapshot
      description: Captures measured workspace outcomes for an existing Financial Operations programme. It does not activate commercial entitlement or transaction authority.
      x-financegpt-scope: commercial:write
      responses:
        '201': {description: Customer-success snapshot captured}
        '422': {description: No Financial Operations programme or invalid window}
  /commercial/restricted-autonomy:
    get:
      summary: Read Restricted Autonomous Operations commercial status
      description: Returns application-only institutional commercial programme, annual contract, readiness, activation, renewal and measured operating evidence. Commercial state never grants admission, certification, mandate approval or autonomous execution authority.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Restricted Autonomous Operations commercial status}
  /commercial/restricted-autonomy/request:
    post:
      summary: Request Restricted Autonomous Operations commercial review
      description: Opens a sales-assisted institutional commercial programme for an existing autonomy application. This is not self-service checkout and payment never guarantees admission.
      x-financegpt-scope: commercial:write
      responses:
        '201': {description: Institutional commercial review requested}
        '422': {description: Invalid request or missing institutional application}
  /commercial/restricted-autonomy/readiness:
    get:
      summary: Read Restricted Autonomous Operations commercial readiness
      description: Returns evidence-backed commercial, Financial Operations, certification, assurance, reconciliation, platform-control and renewal readiness.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Current restricted-autonomy commercial readiness}
  /commercial/restricted-autonomy/value:
    get:
      summary: Read measured Restricted Autonomous Operations outcomes
      description: Returns measured autonomous actions, reconciliation, human interventions, exceptions and currency-separated governed value.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Latest restricted-autonomy customer-success snapshot}
  /commercial/restricted-autonomy/snapshot:
    post:
      summary: Capture Restricted Autonomous Operations measured outcomes
      description: Captures a measured customer-success snapshot for an existing institutional programme. It grants no financial or autonomous authority.
      x-financegpt-scope: commercial:write
      responses:
        '200': {description: Customer-success snapshot captured}
        '404': {description: Commercial programme not found}
  /commercial/restricted-autonomy/renewal:
    get:
      summary: Read Restricted Autonomous Operations renewal status
      description: Returns annual commercial renewal timing and contract state. Renewal does not extend institutional assessment or certification automatically.
      x-financegpt-scope: commercial:read
      responses:
        '200': {description: Restricted Autonomous Operations renewal status}
  /trust/evidence:
    get:
      summary: Read FinanceGPT enterprise trust evidence
      description: Returns aggregate measured Trust Center evidence and provenance posture. Public and API evidence excludes customer transaction payloads, raw prompts, provider credentials and private signing keys.
      x-financegpt-scope: trust:read
      responses:
        '200': {description: Aggregate trust evidence and provenance policy posture}
  /trust/provenance:
    get:
      summary: Read workspace AI-content provenance records
      description: Returns workspace provenance state, disclosure requirements, SHA-256 evidence and machine-marking status without returning private signing key material.
      x-financegpt-scope: trust:read
      responses:
        '200': {description: Workspace content-provenance records}
    post:
      summary: Register governed AI-content provenance
      description: Creates a provenance record and determines visible-disclosure and machine-marking requirements from the configured internal policy profile. Registration does not itself publish or claim C2PA verification.
      x-financegpt-scope: trust:write
      responses:
        '201': {description: Provenance record created}
        '422': {description: Invalid provenance request}
  /trust/evidence-packs:
    post:
      summary: Create a sealed workspace enterprise-evidence pack
      description: Creates a SHA-256 sealed evidence package from current governed trust evidence. The package contains aggregate control evidence and excludes customer transaction payloads, raw prompts, provider credentials and private signing keys.
      x-financegpt-scope: trust:write
      responses:
        '201': {description: Sealed workspace evidence pack created}
  /trust/verify:
    post:
      summary: Verify recorded FinanceGPT provenance evidence
      description: Verifies a FinanceGPT provenance UID and optional final-content/manifest SHA-256 values against recorded evidence. A configured pipeline is not represented as C2PA verified until verification evidence exists.
      x-financegpt-scope: trust:read
      responses:
        '200': {description: Provenance verification result}
        '422': {description: Invalid verification request}
  /agent-execution/capabilities:
    get:
      summary: Read signed external-agent execution capabilities
      description: Returns the operations and financial-action scopes available to the authenticated signed execution client. External client identity authenticates the caller but does not grant transaction authority.
      x-financegpt-scope: agent:execution:read
      responses:
        '200': {description: Agent execution capabilities}
  /agent-execution/proposals:
    post:
      summary: Propose a governed Financial Action from an external agent
      description: Creates a governed Financial Action proposal. Machine-authorized proposals require separately valid Machine Authority evidence; ordinary external-agent proposals remain subject to human authority and approval.
      x-financegpt-scope: agent:execution:propose
      responses:
        '201': {description: Financial Action proposal recorded}
        '422': {description: Proposal rejected by scope or Financial Actions controls}
  /agent-execution/requests/{uid}:
    get:
      summary: Read agent-execution request evidence
      x-financegpt-scope: agent:execution:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Agent-execution request evidence}
  /agent-execution/actions/{uid}:
    get:
      summary: Read governed Financial Action status
      description: Returns the Financial Action control state and reconciliation status without transaction credentials.
      x-financegpt-scope: agent:execution:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Financial Action status}
  /agent-execution/actions/{uid}/submit:
    post:
      summary: Submit an external-agent Financial Action for approval
      description: Enters the normal Financial Actions approval lifecycle; the external client receives no approval authority from this endpoint.
      x-financegpt-scope: agent:execution:submit
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Financial Action submitted for governed approval}
        '422': {description: Submission rejected by Financial Actions controls}
  /agent-execution/actions/{uid}/execute:
    post:
      summary: Request execution of an already-authorized Financial Action
      description: Dispatches only through the existing Financial Actions execution boundary. Machine-delegated execution requires fresh signed Machine Authority evidence and autonomous live remains subject to Restricted Autonomous Operations.
      x-financegpt-scope: agent:execution:execute
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Execution request accepted; reconciliation remains the completion boundary}
        '422': {description: Execution not authorized or control gate failed}
  /agent-execution/actions/{uid}/reconciliation:
    get:
      summary: Read Financial Action reconciliation evidence
      description: Returns settlement/reconciliation state. Execution acknowledgement alone is not represented as completion.
      x-financegpt-scope: agent:execution:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Reconciliation evidence}
  /agent-execution/actions/{uid}/assurance:
    get:
      summary: Read Financial Actions assurance evidence
      description: Returns aggregate workspace assurance and the action envelope hash without customer transaction payloads or credentials.
      x-financegpt-scope: agent:execution:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Financial Actions assurance evidence}
  /agent-execution/webhooks:
    get:
      summary: List signed Financial Action and workflow lifecycle webhooks
      x-financegpt-scope: agent:execution:webhooks
      responses:
        '200': {description: Webhook registrations}
    post:
      summary: Register a signed HTTPS Financial Action or workflow lifecycle webhook
      description: Webhook secrets are returned once and stored encrypted; production endpoints require separate approval and are SSRF screened. Supported events include governed Financial Action lifecycle events plus workflow.invoked, workflow.awaiting_review, workflow.completed, workflow.cancelled and workflow.failed.
      x-financegpt-scope: agent:execution:webhooks
      responses:
        '201': {description: Webhook registered}
        '422': {description: Invalid or unsafe endpoint}
  /agent-execution/webhooks/{uid}:
    delete:
      summary: Revoke an agent-execution lifecycle webhook
      x-financegpt-scope: agent:execution:webhooks
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Webhook revoked}
  /agent-execution/mcp:
    post:
      summary: Invoke the signed FinanceGPT Financial Actions MCP execution gateway
      description: Provides signed-client MCP access to governed Financial Action propose/status/submit/execute/reconciliation/assurance operations. Existing general MCP remains compatible; this endpoint adds external execution-client grants and Ed25519 request signatures.
      x-financegpt-scope: agent:execution:invoke
      responses:
        '200': {description: Governed MCP Financial Actions result}
        '422': {description: Tool outside grant or Financial Actions control boundary}
  /agent-execution/a2a:
    post:
      summary: Invoke the signed FinanceGPT agent-to-agent execution gateway
      description: Dispatches only operations separately allowed by the active signed-client grant; external-agent identity never substitutes for Financial Actions or Machine Authority.
      x-financegpt-scope: agent:execution:invoke
      responses:
        '200': {description: Governed agent-to-agent operation result}
        '422': {description: Operation outside grant or control boundary}
  /agent-execution/service-level:
    get:
      summary: Read active agent-execution service level
      description: Returns rate and monthly request limits for the authenticated signed execution client.
      x-financegpt-scope: agent:execution:read
      responses:
        '200': {description: Service level and limits}
  /agent-execution/usage:
    get:
      summary: Read external-agent execution usage evidence
      description: Returns request and operation evidence. API/MCP commercial billing remains authoritative in the existing usage revenue engine rather than this request log.
      x-financegpt-scope: agent:execution:read
      responses:
        '200': {description: Agent-execution usage evidence}
  /agent-execution/workflows:
    get:
      summary: List published immutable Workflow Studio tools allowed for the signed external agent
      description: Returns only explicitly published, pinned immutable production workflow versions inside the active workflow-specific grant. Discovery does not grant human-review or Financial Action authority.
      x-financegpt-scope: agent:execution:read
      responses:
        '200': {description: Governed workflow tool catalogue}
        '422': {description: No active workflow-specific grant or operation outside scope}
  /agent-execution/workflows/use-cases:
    get:
      summary: List the canonical FinanceGPT workflow use-case catalogue
      description: Returns the 55 governed use cases and their risk/execution posture for external-agent discovery without installing or executing them.
      x-financegpt-scope: agent:execution:read
      responses:
        '200': {description: Canonical use-case catalogue}
  /agent-execution/workflows/tools/{uid}/runs:
    post:
      summary: Invoke a published immutable production workflow
      description: Starts an asynchronous S4 Workflow Studio run through an explicit external-agent workflow grant. Human-review nodes remain human and Financial Action nodes enter the canonical Financial Actions control plane.
      x-financegpt-scope: agent:execution:invoke
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '202': {description: Workflow invocation accepted}
        '422': {description: Tool, quota, grant or input boundary rejected the invocation}
  /agent-execution/workflows/runs/{uid}:
    get:
      summary: Read an external-agent workflow invocation
      x-financegpt-scope: agent:execution:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Durable Workflow Studio invocation state}
  /agent-execution/workflows/runs/{uid}/cancel:
    post:
      summary: Request cancellation of the client's own non-terminal workflow invocation
      description: Cancellation is available only when the original workflow-specific grant permits it and does not reverse external side effects already governed by their systems of record.
      x-financegpt-scope: agent:execution:invoke
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '202': {description: Cancellation requested}
        '422': {description: Cancellation outside grant or run state}
  /agent-execution/workflows/runs/{uid}/outcome:
    get:
      summary: Read measured workflow outcome evidence
      description: Returns measured run, node, retry, artifact, event and Financial Action outcome evidence. Estimated metrics appear only when an explicitly approved workspace baseline exists and remain labelled estimated.
      x-financegpt-scope: agent:execution:read
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string}}
      responses:
        '200': {description: Workflow outcome evidence}
        '422': {description: Outcome unavailable before terminal run state}
  /agent-execution/workflows/mcp:
    post:
      summary: Invoke the signed Workflow Studio MCP gateway
      description: Supports workflow tool discovery, use-case discovery, invocation, status, cancellation and outcome retrieval under the existing Ed25519 Agent Execution identity and grant controls.
      x-financegpt-scope: agent:execution:invoke
      responses:
        '200': {description: Governed MCP workflow result}
        '202': {description: Workflow invocation accepted}
        '422': {description: Tool or operation outside workflow grant}
  /agent-execution/workflows/a2a:
    post:
      summary: Invoke the signed Workflow Studio agent-to-agent gateway
      description: Dispatches workflow operations only inside an approved base Agent Execution grant plus a separate explicit workflow-tool allowlist.
      x-financegpt-scope: agent:execution:invoke
      responses:
        '200': {description: Governed A2A workflow result}
        '202': {description: Workflow invocation accepted}
        '422': {description: Operation outside grant or workflow control boundary}
  /workflow-event-mesh/{source_uid}:
    post:
      summary: Deliver a signed external event to an immutable Workflow Studio version
      description: Public webhook ingress authenticated with FinanceGPT HMAC v1 headers. The source is workspace-scoped, payloads are encrypted at rest, event IDs are idempotent, production sources pin immutable production workflow versions, and Marketplace-managed workflows cannot bypass Marketplace runtime controls through this endpoint.
      security: []
      parameters:
        - {in: path, name: source_uid, required: true, schema: {type: string, format: uuid}}
        - {in: header, name: X-FinanceGPT-Event-Timestamp, required: true, schema: {type: string}}
        - {in: header, name: X-FinanceGPT-Event-Id, required: true, schema: {type: string, maxLength: 191}}
        - {in: header, name: X-FinanceGPT-Signature, required: true, schema: {type: string}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object, additionalProperties: true}
      responses:
        '202': {description: Event accepted, filtered, dead-lettered, or idempotently acknowledged}
        '401': {description: Signature, timestamp, or signing-secret validation failed}
        '404': {description: Event source not found}
        '409': {description: Event source inactive, version/hash mismatch, or event ID reused with different payload bytes}
        '413': {description: Event payload exceeds source limit}
        '422': {description: Invalid event payload or signed-event headers}
        '429': {description: Source rate limit reached}
        '503': {description: Runtime temporarily busy; retry the same event ID}
  /workflow-studio/operations:
    get:
      summary: Read workspace Workflow Reliability operations, SLO evidence and runtime incidents
      x-financegpt-scope: workflow:read
      responses: {'200': {description: Workflow reliability operations}}
  /workflow-studio/templates/{id}/reliability:
    put:
      summary: Configure a workspace-owned workflow reliability policy
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses: {'200': {description: Reliability policy updated}}
  /workflow-studio/templates/{id}/reliability/hold:
    post:
      summary: Place a local hold on new production starts without cancelling existing runs
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses: {'200': {description: Production hold placed}}
  /workflow-studio/templates/{id}/reliability/release-hold:
    post:
      summary: Release a local workflow production hold after operator review
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses: {'200': {description: Production hold released}}
  /workflow-studio/operations/incidents/{uid}/acknowledge:
    post:
      summary: Acknowledge a workspace Workflow Reliability runtime incident
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses: {'200': {description: Runtime incident acknowledged}}
  /workflow-studio/operations/incidents/{uid}/resolve:
    post:
      summary: Resolve a workspace Workflow Reliability runtime incident
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses: {'200': {description: Runtime incident resolved}}
  /workflow-studio/templates/{id}/change-safety:
    get:
      summary: Read Workflow Studio test suites, validation campaigns and production-promotion safety evidence
      description: Returns metadata only. Encrypted test inputs and assertions are never exposed by this endpoint.
      x-financegpt-scope: workflow:read
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses: {'200': {description: Workflow change-safety status}}
  /workflow-studio/templates/{id}/test-suites:
    post:
      summary: Create a workspace-scoped workflow regression test suite
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: id, required: true, schema: {type: integer}}
      responses: {'201': {description: Test suite created}}
  /workflow-studio/test-suites/{uid}/cases:
    post:
      summary: Add an encrypted workflow test case and assertion contract
      description: Test inputs and assertions are encrypted at rest. Campaign results persist hashes and bounded summaries rather than raw simulated outputs.
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses: {'201': {description: Test case created}}
  /workflow-studio/test-cases/{uid}/toggle:
    post:
      summary: Enable or disable a workflow test case
      description: Changing enabled cases changes the suite fingerprint and invalidates prior campaigns for future production promotion.
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses: {'200': {description: Test case state updated}}
  /workflow-studio/versions/{uid}/validate:
    post:
      summary: Run a side-effect-free S16 validation campaign against an exact draft or testing version
      description: Deterministic computations and conditions may execute locally. Waits and artifacts are virtualized. Agent, Integration, Financial Action, code-runner, sub-workflow and external network execution are prohibited.
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses:
        '202': {description: Validation campaign completed with durable evidence}
        '422': {description: Invalid suite, assertion contract or version state}
  /workflow-studio/validation-campaigns/{uid}/review:
    post:
      summary: Explicitly approve or reject a high-risk workflow change after successful validation
      description: Review does not promote the workflow. Production promotion remains a separate explicit action and revalidates the exact version, production baseline and suite fingerprint.
      x-financegpt-scope: workflow:manage
      parameters:
        - {in: path, name: uid, required: true, schema: {type: string, format: uuid}}
      responses: {'200': {description: Change-safety review recorded}}
  /workflow-studio/finops:
    get:
      tags: [Workflow Studio]
      summary: Read Workflow FinOps and capacity intelligence
      responses: {'200': {description: Workflow FinOps status}}
  /workflow-studio/finops/refresh:
    post:
      tags: [Workflow Studio]
      summary: Refresh workflow cost attribution and capacity evidence
      responses: {'200': {description: Workflow FinOps refreshed without automatic capacity changes}}
  /workflow-studio/finops/policy:
    put:
      tags: [Workflow Studio]
      summary: Update observational Workflow FinOps policy
      responses: {'200': {description: Workflow FinOps policy updated}}
  /workflow-studio/templates/{id}/finops-policy:
    put:
      tags: [Workflow Studio]
      summary: Update workflow-specific observational FinOps policy
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses: {'200': {description: Workflow FinOps policy updated}}
  /workflow-studio/finops/alerts/{uid}/acknowledge:
    post:
      tags: [Workflow Studio]
      summary: Acknowledge a Workflow FinOps alert
      parameters:
        - {name: uid, in: path, required: true, schema: {type: string}}
      responses: {'200': {description: Alert acknowledged}}
  /workflow-studio/finops/alerts/{uid}/resolve:
    post:
      tags: [Workflow Studio]
      summary: Resolve a Workflow FinOps alert
      parameters:
        - {name: uid, in: path, required: true, schema: {type: string}}
      responses: {'200': {description: Alert resolved}}

  /workflow-studio/admission:
    get:
      tags: [Workflow Studio]
      summary: Read workload admission policy, capacity context and recent decisions
      x-financegpt-scope: workflow:read
      responses: {'200': {description: Workflow admission control status}}
  /workflow-studio/admission/decisions:
    get:
      tags: [Workflow Studio]
      summary: Read recent durable workflow admission decisions
      x-financegpt-scope: workflow:read
      responses: {'200': {description: Recent admission decisions}}
  /workflow-studio/admission/policy:
    put:
      tags: [Workflow Studio]
      summary: Update the workspace workload admission policy
      description: Observe mode records pressure without blocking. Enforce mode must be explicitly configured and affects only new workflow starts. It does not change worker counts or topology.
      x-financegpt-scope: workflow:manage
      responses: {'200': {description: Workspace admission policy updated}}
  /workflow-studio/templates/{id}/admission-policy:
    put:
      tags: [Workflow Studio]
      summary: Update a workflow-specific admission policy and policy-controlled priority class
      description: API callers cannot self-select runtime priority. Priority is taken only from the stored workspace or workflow policy.
      x-financegpt-scope: workflow:manage
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses: {'200': {description: Workflow admission policy updated}}

  /workflow-studio/qos:
    get:
      tags: [Workflow Studio]
      summary: Read Workflow Queue QoS policy, latest fairness evidence and recent dispatch decisions
      description: S20 Observe preserves FIFO dispatch while recording weighted-fair shadow ordering. Enforce uses weighted-fair ordering after S19 admission.
      x-financegpt-scope: workflow:read
      responses: {'200': {description: Workflow Queue QoS status}}
  /workflow-studio/qos/decisions:
    get:
      tags: [Workflow Studio]
      summary: Read recent durable S20 dispatch decisions
      x-financegpt-scope: workflow:read
      responses: {'200': {description: Recent queue QoS dispatch decisions}}
  /workflow-studio/qos/policy:
    put:
      tags: [Workflow Studio]
      summary: Update workspace weighted-fair dispatch and queue-age QoS policy
      description: Policy changes do not alter S19 admission priority, worker counts, topology, queue backend, billing or Financial Action authority.
      x-financegpt-scope: workflow:manage
      responses: {'200': {description: Workspace queue QoS policy updated}}
  /workflow-studio/templates/{id}/qos-policy:
    put:
      tags: [Workflow Studio]
      summary: Update workflow-specific weighted-fair dispatch and queue-age QoS policy
      x-financegpt-scope: workflow:manage
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses: {'200': {description: Workflow queue QoS policy updated}}

  /lqm/models/{uid}/operations-policy:
    get:
      summary: Read governed LQM training operations policy
      description: Returns drift cadence, deterministic thresholds, cooldown, evaluation age policy and the mandatory human-review boundary.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: LQM operations policy or null when not configured}
    put:
      summary: Configure LQM drift and retraining operations
      description: Configures monitoring and retraining-request policy. This never changes the active model version and never grants automatic promotion.
      x-financegpt-scope: lqm:build:write
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [cadence]
              properties:
                cadence: {type: string, enum: [daily, weekly, monthly]}
                scheduled_retraining_enabled: {type: boolean}
                drift_monitoring_enabled: {type: boolean}
                automatic_request_creation: {type: boolean}
                cooldown_hours: {type: integer, minimum: 1, maximum: 8760}
                evaluation_max_age_days: {type: integer, minimum: 1, maximum: 3650}
                thresholds: {type: object, additionalProperties: true}
      responses:
        '200': {description: Governed operations policy sealed with SHA-256}
        '409': {description: Invalid policy or LQM context}
  /lqm/models/{uid}/drift-assessments:
    get:
      summary: List LQM drift assessments
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Deterministic data/model-quality drift evidence}
    post:
      summary: Run deterministic LQM drift assessment
      description: Compares a newer governed numeric dataset with the latest passing evaluated checkpoint, records metric evidence in the existing ML drift store and may create a review-gated retraining request.
      x-financegpt-scope: lqm:build:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dataset_id]
              properties:
                dataset_id: {type: integer, minimum: 1}
      responses:
        '201': {description: Drift assessment sealed with SHA-256}
        '409': {description: Dataset or evaluated checkpoint is ineligible}
  /lqm/models/{uid}/retraining-requests:
    get:
      summary: List governed LQM retraining requests
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Review-gated retraining requests and candidate state}
    post:
      summary: Create an LQM retraining request
      description: Creates a human-review request against a governed numeric dataset without starting training or changing active_version_id.
      x-financegpt-scope: lqm:build:write
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dataset_id]
              properties:
                dataset_id: {type: integer, minimum: 1}
                reason_code: {type: string, maxLength: 64}
      responses:
        '201': {description: Retraining request created in pending review state}
        '409': {description: Retraining request rejected by policy or lineage checks}
  /lqm/retraining-requests/{requestUid}/decision:
    post:
      summary: Decide an LQM retraining request
      description: Explicit human approval authorizes candidate training only. Reject and cancel remain non-executing decisions; none of these operations promote or activate a checkpoint.
      x-financegpt-scope: lqm:build:write
      parameters: [{in: path, name: requestUid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: {type: string, enum: [approve, reject, cancel]}
                note: {type: string, maxLength: 2000}
      responses:
        '200': {description: Review decision recorded}
        '409': {description: Request is not in a reviewable state}
  /lqm/retraining-requests/{requestUid}/advance:
    post:
      summary: Advance an approved LQM retraining lifecycle
      description: Advances only an explicitly approved request through sealed training and the required evaluation suite. A passing result becomes candidate_ready for a separate governed promotion review; active_version_id remains unchanged by retraining.
      x-financegpt-scope: lqm:build:run
      parameters: [{in: path, name: requestUid, required: true, schema: {type: string}}]
      responses:
        '202': {description: Retraining lifecycle advanced or remains waiting on queued compute}
        '409': {description: Training or evaluation lineage failed}
  /lqm/models/{uid}/publications:
    get:
      summary: List governed model-hub publications for an LQM
      description: Returns publication state, builder attribution, repository revision and immutable supply-chain hashes. Publication does not activate or promote the checkpoint inside FinanceGPT.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: LQM model-hub publication history and supply-chain evidence}
        '404': {description: LQM not found in this workspace}
  /lqm/models/{uid}/publish:
    post:
      summary: Publish an evaluated LQM checkpoint to the configured model hub
      description: Requires an attributable human builder, an active workspace publishing connection, exact sealed checkpoint lineage, all required evaluation gates passing, an independently verified Evidence Packet, acceptable drift posture and explicit confirmation of the selected checkpoint and license. Publishing never changes an active model version or QLM binding.
      x-financegpt-scope: lqm:publish:write
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model_version_id, license, human_confirmation]
              properties:
                model_version_id: {type: integer, minimum: 1}
                license: {type: string, maxLength: 96}
                repository_name: {type: string, nullable: true, maxLength: 96}
                visibility: {type: string, enum: [public, private], default: public}
                human_confirmation: {type: boolean, enum: [true], description: 'Explicit confirmation of the exact checkpoint, license and disclosure package'}
      responses:
        '202': {description: Governed model-hub publication queued}
        '403': {description: No attributable human creator is available for the API application}
        '409': {description: 'Publishing rejected by connection, evaluation, evidence, drift, repository or human-confirmation controls'}
  /lqm/publications/{publicationUid}:
    get:
      summary: Read an LQM model-hub publication and supply-chain evidence
      description: Returns repository identity and revision, checkpoint/evaluation/Evidence Packet hashes, builder attribution, publication bundle hashes, remote artifact hashes and the hash-linked supply-chain head. Credential material is never returned.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: publicationUid, required: true, schema: {type: string}}]
      responses:
        '200': {description: LQM publication record and immutable artifact evidence}
        '404': {description: Publication not found in this workspace}
  /lqm/models/{uid}/promotions:
    get:
      summary: List governed LQM promotions for a workspace model
      description: Returns promotion decisions that project exact evaluated LQM checkpoints into the workspace Quant Models catalog.
      x-financegpt-scope: lqm:build:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: LQM promotion history and control evidence}
  /lqm/models/{uid}/promote:
    post:
      summary: Promote an evaluated LQM checkpoint into Quant Models
      description: Requires an attributable human approver, a passing evaluation, a verified Evidence Packet and an acceptable drift posture. Promotion may activate the exact governed ML and Quant Models version but never grants language or Financial Actions authority.
      x-financegpt-scope: lqm:promote:write
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model_version_id, human_confirmation]
              properties:
                model_version_id: {type: integer, minimum: 1}
                human_confirmation: {type: boolean, enum: [true], description: Explicit human confirmation of the exact promotion decision}
                decision_note: {type: string, maxLength: 2000}
      responses:
        '201': {description: Exact LQM checkpoint promoted into Quant Models}
        '409': {description: Promotion rejected by evaluation, evidence, drift or human-approval controls}
  /lqm/promotions/{promotionUid}/retire:
    post:
      summary: Retire an active LQM Quant Models promotion
      description: Human retirement disables the promoted Quant Models version. Existing QLM versions remain immutable and fail closed rather than silently rebinding to another checkpoint.
      x-financegpt-scope: lqm:promote:write
      parameters: [{in: path, name: promotionUid, required: true, schema: {type: string}}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                decision_note: {type: string, maxLength: 2000}
      responses:
        '200': {description: Promotion retired}
        '409': {description: Promotion is not active or cannot be retired}
  /lqm/commercial-model:
    get:
      summary: Read the governed LQM commercial model
      description: Returns product-policy categories and authority guardrails. It does not assert a model is FinanceGPT-trained without supporting provenance and does not enable billing.
      x-financegpt-scope: lqm:build:read
      responses:
        '200': {description: LQM commercial categories and guardrails}
  /lqm/usage-evidence:
    get:
      summary: Read workspace LQM usage evidence
      description: Returns permission-scoped LQM training, evaluation, inference, QLM Evidence Packet usage and explicitly recorded workflow-outcome measurements for the current workspace.
      x-financegpt-scope: lqm:build:read
      parameters:
        - {in: query, name: days, required: false, schema: {type: integer, minimum: 1, maximum: 365, default: 30}}
      responses:
        '200': {description: Workspace LQM usage evidence}
  /lqm/workflow-outcomes:
    post:
      summary: Record a workspace LQM workflow outcome observation
      description: Records an explicitly supplied measurement such as paired manual and assisted duration, task success, business-unit attribution or avoided premium calls. The observation is self-reported and remains unverified until separately reviewed.
      x-financegpt-scope: lqm:build:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source_reference]
              properties:
                source_reference: {type: string, maxLength: 191}
                business_unit_key: {type: string, maxLength: 96}
                model_id: {type: integer, minimum: 1}
                model_version_id: {type: integer, minimum: 1}
                manual_duration_ms: {type: integer, minimum: 0, maximum: 86400000}
                assisted_duration_ms: {type: integer, minimum: 0, maximum: 86400000}
                task_success: {type: boolean}
                quality_score_bps: {type: integer, minimum: 0, maximum: 10000}
                avoided_premium_calls: {type: integer, minimum: 0}
                cost_minor: {type: integer, minimum: 0}
                currency: {type: string, minLength: 3, maxLength: 3}
                evidence_reference: {type: string, maxLength: 512}
      responses:
        '201': {description: Self-reported LQM workflow-outcome observation recorded}
        '422': {description: Workflow-outcome evidence rejected by validation controls}
  /investment/theme-watch:
    get:
      summary: Read Thematic Factor Model and Theme Watch evidence
      description: Returns workspace-scoped point-in-time thematic factor runs, descriptive factor-return summaries, specific-risk estimates and exposure-weighted FinanceGPT research indices. Outputs use observed provider market history and version-pinned source-backed thematic exposures; they are not forecasts, expected returns, external benchmarks or execution instructions.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: run_id, required: false, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: Theme Watch research evidence}
  /investment/theme-watch/factors:
    post:
      summary: Estimate point-in-time thematic factor returns
      description: Runs the governed financegpt_theme_factor_ridge_v1 cross-sectional model on observed monthly market history and the latest taxonomy version published by the requested as-of date. It also derives descriptive specific risk and exposure-weighted theme indices. No synthetic market data, portfolio rebalance, Financial Action or trade is created.
      x-financegpt-scope: investment:run
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                as_of_date: {type: string, format: date}
                history_months: {type: integer, minimum: 12, maximum: 120, default: 36}
                ridge_lambda: {type: number, minimum: 0.000001, maximum: 100, default: 0.1}
                minimum_symbols_per_factor: {type: integer, minimum: 3, maximum: 50, default: 3}
                max_factors: {type: integer, minimum: 1, maximum: 50, default: 25}
                max_symbols: {type: integer, minimum: 10, maximum: 250, default: 120}
      responses:
        '201': {description: Thematic factor run sealed with SHA-256 market, exposure and result evidence}
        '503': {description: Point-in-time taxonomy exposure or observed market history coverage is insufficient}
  /investment/portfolios/{portfolio}/theme-watch:
    post:
      summary: Seal a portfolio thematic attribution and drift snapshot
      description: Maps provider-valued current portfolio weights through source-backed thematic exposures, links the latest selected factor observation for static attribution and measures thematic concentration and drift versus the previous snapshot under the same taxonomy version. The snapshot is research evidence only and does not rebalance the portfolio or create a Financial Action.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                run_id: {type: integer, minimum: 1}
      responses:
        '201': {description: Portfolio Theme Watch snapshot sealed}
        '503': {description: Factor run, portfolio valuation or thematic exposure evidence is unavailable}
  /investment/themes/universes/{universe}/analytics:
    get:
      summary: Read saved thematic-universe analytics
      description: Returns concentration metrics for an immutable Concept2Universe universe plus linked Theme Watch factor and research-index evidence when a compatible factor run exists. The analytics do not claim thematic relevance as expected return or performance.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: universe, required: true, schema: {type: integer, minimum: 1}}
        - {in: query, name: run_id, required: false, schema: {type: integer, minimum: 1}}
      responses:
        '200': {description: Saved thematic-universe analytics and linked factor evidence}
  /investment/book:
    get:
      summary: Read the workspace investment book control surface
      description: Returns portfolio-scoped book positions, cash projections, settlement obligations, corporate-action cases, NAV snapshots and existing reconciliation breaks. Financial Actions remains the sole execution authority.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, required: false, schema: {type: string}}
      responses:
        '200': {description: Investment book and front-to-back operating evidence}
  /investment/portfolios/{portfolio}/book/seed:
    post:
      summary: Seed an empty portfolio book from opening evidence
      description: Captures current legacy portfolio assets as opening position evidence and optionally accepts explicit opening cash evidence. This is accounting initialization only and does not execute a trade or Financial Action.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cash_balances:
                  type: array
                  maxItems: 20
                  items:
                    type: object
                    required: [currency, amount_minor, source_reference]
                    properties:
                      currency: {type: string, minLength: 3, maxLength: 8}
                      amount_minor: {type: integer}
                      amount_scale: {type: integer, minimum: 0, maximum: 8, default: 2}
                      source_reference: {type: string, maxLength: 191}
                      source_hash: {type: string, minLength: 64, maxLength: 64}
      responses:
        '201': {description: Opening book evidence recorded and projection sealed}
        '422': {description: Book already contains entries or opening evidence is invalid}
  /investment/portfolios/{portfolio}/book/synchronize:
    post:
      summary: Synchronize governed trade and settlement evidence into the investment book
      description: Imports new Financial Action investment trade confirmations, reflects authoritative reconciliation settlement state, discovers applicable Financial Data Cloud corporate actions and rebuilds position/cash projections. It never resubmits or retries execution.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      responses:
        '201': {description: Front-to-back synchronization completed}
  /investment/portfolios/{portfolio}/book/nav:
    post:
      summary: Seal an observed-data portfolio NAV snapshot
      description: Values settled book positions and cash using only observed Market Data Gateway quotes and FX. Missing required market data fails closed; pending settlement cash is disclosed separately and excluded from settled NAV.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reporting_currency: {type: string, minLength: 3, maxLength: 8, default: USD}
      responses:
        '201': {description: SHA-256-sealed observed-data NAV snapshot}
        '503': {description: Required observed quote or FX evidence is unavailable}
  /investment/portfolios/{portfolio}/book/reconcile:
    post:
      summary: Reconcile settled investment-book positions to the latest custodian import
      description: Compares IM10 settled quantities to the existing custodian position snapshot and writes differences into the existing investment reconciliation-break control plane. No settlement instruction is sent.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      responses:
        '201': {description: Book-to-custody reconciliation completed}
        '503': {description: No reconciled custodian position import is available}
  /investment/portfolios/{portfolio}/book/operations:
    get:
      summary: Read portfolio front-to-back operating state
      description: Returns current IM10 positions, cash, settlement obligations, corporate-action cases, NAV snapshots and operational reconciliation breaks without changing execution state.
      x-financegpt-scope: investment:read
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      responses:
        '200': {description: Portfolio front-to-back operating state}
  /investment/portfolios/{portfolio}/book/nav-snapshots:
    get:
      summary: Read sealed portfolio NAV snapshots
      description: Returns recent observed-data IM10 NAV evidence for the portfolio. Synthetic market data is never used for these snapshots.
      x-financegpt-scope: investment:read
      parameters:
        - {in: path, name: portfolio, required: true, schema: {type: string}}
        - {in: query, name: limit, required: false, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses:
        '200': {description: Recent sealed NAV snapshots}
  /investment/collateral-xva:
    get:
      summary: Read collateral, margin, treasury and XVA operating evidence
      description: Returns workspace-scoped netting sets, explicit collateral-eligibility policy, margin calls, non-executable allocation proposals, observed collateral inventory, treasury capacity and recent counterparty/XVA evidence. No collateral or cash transfer is initiated.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, required: false, schema: {type: string}}
      responses:
        '200': {description: IM11 operating evidence}
  /investment/collateral-xva/netting-sets:
    post:
      summary: Record an evidence-backed netting set
      description: Records explicit bilateral or other agreement terms used by IM11 analytics. FinanceGPT does not infer legal enforceability or agreement thresholds.
      x-financegpt-scope: investment:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, currency, source_reference]
              properties:
                name: {type: string, maxLength: 191}
                counterparty_id: {type: integer, minimum: 1}
                agreement_type: {type: string, maxLength: 64, default: bilateral}
                currency: {type: string, minLength: 3, maxLength: 8}
                threshold_minor: {type: integer, minimum: 0}
                minimum_transfer_minor: {type: integer, minimum: 0}
                independent_amount_minor: {type: integer, minimum: 0}
                amount_scale: {type: integer, minimum: 0, maximum: 8, default: 2}
                source_reference: {type: string, maxLength: 191}
                source_hash: {type: string, minLength: 64, maxLength: 64}
      responses:
        '201': {description: Netting-set evidence recorded}
  /investment/collateral-xva/rules:
    post:
      summary: Record a collateral eligibility and haircut rule
      description: Records explicit cash/security eligibility, haircut and HQLA classification evidence. Unmatched collateral remains ineligible and unclassified by default.
      x-financegpt-scope: investment:run
      responses:
        '201': {description: Collateral rule recorded}
  /investment/portfolios/{portfolio}/collateral-inventory:
    post:
      summary: Seal observed collateral and HQLA inventory
      description: Values settled IM10 book securities and positive cash using observed Market Data Gateway quotes/FX, then applies explicit IM11 eligibility/haircut policy. Synthetic market data is never substituted.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: portfolio, required: true, schema: {type: string}}]
      responses:
        '201': {description: SHA-256-sealed collateral inventory snapshot}
        '503': {description: Required observed market data is unavailable}
  /investment/collateral-xva/netting-sets/{nettingSet}/margin-calls:
    post:
      summary: Record a margin-call evidence item
      description: Records source-referenced margin-call evidence and status. It does not send a margin call, transfer collateral or move cash.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: nettingSet, required: true, schema: {type: integer, minimum: 1}}]
      responses:
        '201': {description: Margin-call evidence recorded}
  /investment/portfolios/{portfolio}/margin-calls/{call}/collateral-proposal:
    post:
      summary: Generate a non-executable collateral allocation proposal
      description: Revalues the current IM10 portfolio inventory under the margin-call currency, applies explicit eligibility/haircuts and greedily preserves HQLA while minimizing haircut. The proposal cannot initiate a custody or payment instruction.
      x-financegpt-scope: investment:run
      parameters:
        - {in: path, name: portfolio, required: true, schema: {type: string}}
        - {in: path, name: call, required: true, schema: {type: integer, minimum: 1}}
      responses:
        '201': {description: Non-executable collateral proposal sealed}
        '422': {description: Margin call or collateral evidence is insufficient}
  /investment/collateral-xva/netting-sets/{nettingSet}/exposure:
    post:
      summary: Seal explicit counterparty/netting-set exposure evidence
      description: Nets explicit source-referenced mark-to-market and add-on inputs under the selected netting set and explicit collateral balances. It is not an SA-CCR or legal enforceability determination.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: nettingSet, required: true, schema: {type: integer, minimum: 1}}]
      responses:
        '201': {description: Counterparty exposure foundation sealed}
  /investment/collateral-xva/exposures/{exposure}/xva:
    post:
      summary: Calculate deterministic CVA/DVA/FVA/MVA foundations
      description: Applies explicit horizon PD/LGD, funding-spread, discount-rate and initial-margin inputs to a sealed IM11 exposure snapshot. This is a bounded deterministic XVA foundation, not full trade revaluation or regulatory capital.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: exposure, required: true, schema: {type: integer, minimum: 1}}]
      responses:
        '201': {description: SHA-256-sealed XVA foundation snapshot}
  /investment/governed-ai-operations:
    get:
      summary: List governed AI investment operations
      description: Returns workspace-scoped evidence-governed investment operations. The surface composes existing thematic, LQM/generative, risk, collateral/XVA and downstream Financial Action evidence without creating execution authority.
      x-financegpt-scope: investment:read
      parameters:
        - {in: query, name: portfolio_id, required: false, schema: {type: string}}
      responses:
        '200': {description: Governed AI investment operation register}
    post:
      summary: Create a shadow or governed-review investment operation
      description: Creates an evidence workflow only. Shadow mode can never hand off an action. Governed review still requires sealed evidence, an approved model portfolio and the existing human approval and execution control planes.
      x-financegpt-scope: investment:run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [portfolio_id, mode, title]
              properties:
                portfolio_id: {type: string}
                mode: {type: string, enum: [shadow, governed_review]}
                title: {type: string, maxLength: 191}
                investment_thesis: {type: string, maxLength: 10000}
                thematic_universe_id: {type: integer, minimum: 1}
                model_portfolio_id: {type: integer, minimum: 1}
                synthetic_option_run_id: {type: integer, minimum: 1}
                xva_snapshot_id: {type: integer, minimum: 1}
                require_thematic: {type: boolean, default: true}
                require_theme_watch: {type: boolean, default: true}
                require_lqm: {type: boolean, default: false}
                require_generative_markets: {type: boolean, default: true}
                require_collateral_xva: {type: boolean, default: false}
                max_evidence_age_hours: {type: integer, minimum: 1, maximum: 720, default: 72}
      responses:
        '201': {description: Governed AI investment operation created}
        '422': {description: Evidence references or operation configuration rejected}
  /investment/governed-ai-operations/{uid}:
    get:
      summary: Read a governed AI investment operation and evidence graph
      description: Returns the sealed/live upstream evidence graph, readiness gates, append-only operation events and downstream approval/execution linkage.
      x-financegpt-scope: investment:read
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Governed AI investment operation detail}
  /investment/governed-ai-operations/{uid}/refresh:
    post:
      summary: Synchronize governed investment evidence and downstream state
      description: Before sealing, refreshes the latest eligible upstream evidence. After sealing, upstream evidence remains pinned and only downstream proposal, order-batch, Financial Action and reconciliation state is synchronized.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '200': {description: Operation synchronized}
  /investment/governed-ai-operations/{uid}/seal:
    post:
      summary: Seal the governed upstream investment evidence packet
      description: Requires every configured evidence gate to pass. The SHA-256 evidence packet is immutable for action handoff. Sealing does not approve or execute anything.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '201': {description: Evidence packet sealed}
        '422': {description: Required evidence is missing or stale}
  /investment/governed-ai-operations/{uid}/rebalance:
    post:
      summary: Create a governed rebalance proposal from sealed evidence
      description: Available only to governed-review operations with a human-approved model portfolio. Reuses the existing rebalance engine, observed market data and pre-trade controls. It does not create an order batch or Financial Action.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '201': {description: Non-executable rebalance proposal created}
        '422': {description: Operation, model approval or pre-trade controls reject proposal creation}
  /investment/governed-ai-operations/{uid}/submit:
    post:
      summary: Request human approval for the governed rebalance proposal
      description: Submits the existing rebalance proposal to FinanceGPT's human approval workflow. It cannot approve itself, create an order batch, submit broker orders or execute a Financial Action.
      x-financegpt-scope: investment:run
      parameters: [{in: path, name: uid, required: true, schema: {type: string}}]
      responses:
        '201': {description: Human approval requested}
        '422': {description: Proposal cannot be submitted}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: FinanceGPT API key or OAuth service token
