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/portfolios/{portfolio}/construct:
    post:
      summary: Run governed quantitative portfolio construction
      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]}
                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}
                create_model_portfolio: {type: boolean}
                model_name: {type: string, maxLength: 191}
                benchmark_symbol: {type: string, maxLength: 32}
      responses:
        '201': {description: Construction evidence created; no order placed}
        '422': {description: Invalid input or insufficient governed market evidence}
  /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}
  /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}/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}}

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: FinanceGPT API key or OAuth service token
