K-φ (K-Phi) Get Valuation API

openapi: 3.2.0
info:
  title: K-φ Get Valuation API
  version: 1.0.0
  description: 'Read your K-φ data (statements, cash, forecasts, scenarios) and save scenarios. The tenant always comes from the credential. Every response is { data, meta }; every error { error: { code, message } }.'
tags:
- name: Get Valuation
paths:
  /api/v1/get_valuation:
    get:
      operationId: get_get_valuation
      summary: One valuation case
      x-audience: data
      description: 'Get a company valuation: the reconciled equity value WITH its range, the value by method (DCF, comparables) and their weights, enterprise value, net debt, WACC, the key assumptions with where each came from (the ledger, measured from invoices and bank, a market dataset, or typed by the user), warnings, and a quality block. Always quote the range with the value, name assumed inputs, and never present the result as a certified valuation.'
      x-scope: read:forecast
      x-extension-only: false
      security:
      - bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  meta:
                    type: object
                    properties:
                      api:
                        type: string
                      capability:
                        type: string
                      at:
                        type: string
        '401':
          description: No or invalid credential
        '403':
          description: Scope, extension or Builder Mode refused
        '422':
          description: The capability refused the input
        '429':
          description: Rate or daily quota reached
      parameters:
      - name: case_id
        in: query
        required: false
        description: The valuation case id, from kphi_list_valuations.
        schema:
          type: string
      tags:
      - Get Valuation
    post:
      operationId: post_get_valuation
      summary: One valuation case
      x-audience: data
      description: 'Get a company valuation: the reconciled equity value WITH its range, the value by method (DCF, comparables) and their weights, enterprise value, net debt, WACC, the key assumptions with where each came from (the ledger, measured from invoices and bank, a market dataset, or typed by the user), warnings, and a quality block. Always quote the range with the value, name assumed inputs, and never present the result as a certified valuation.'
      x-scope: read:forecast
      x-extension-only: false
      security:
      - bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  meta:
                    type: object
                    properties:
                      api:
                        type: string
                      capability:
                        type: string
                      at:
                        type: string
        '401':
          description: No or invalid credential
        '403':
          description: Scope, extension or Builder Mode refused
        '422':
          description: The capability refused the input
        '429':
          description: Rate or daily quota reached
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                case_id:
                  type: string
                  description: The valuation case id, from kphi_list_valuations.
              required:
              - case_id
              additionalProperties: false
      tags:
      - Get Valuation
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key, OAuth access token, extension key (kphix_…) or extension session token (kxs1.…)
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key with the gl:ingest scope (ERP connectors)
x-scopes:
  gl:ingest: Push GL data from an ERP (/api/gl/mappings, /api/gl/schema, /api/gl/ingest)
  mcp:tools: All read scopes (read:gl read:cash read:forecast read:sheets read:data)
  mcp:write: All MCP write scopes (write:scenarios write:config write:data write:sheets)
  read:gl: Read statements, KPIs, ratios, GL lines, versions, dimensions, variance, data lake, FX rates and FP&A settings
  read:cash: Read bank positions, transactions, balance history, cash forecast, AR/AP
  read:forecast: Read forecasts, budgets, scenarios (levers, list, run) and valuations
  read:sheets: Read the Google Sheets registered as inputs of the account, each tab as JSON (/api/v1/sheets/…), and their webhooks' deliveries (2026-11-02)
  write:sheets: 'Register and remove the Google Sheets the account serves as JSON (read only: K-φ never writes to a sheet), and the webhooks told when one changes'
  read:data: 'Read the Data library (/api/v1/data/…): market, macro and public series with their source and licence (2026-11-03)'
  write:vars: 'Define, load and remove the account''s own variables (var.<CODE>) of the Data library, and nothing else: never the books (2026-11-05)'
  write:scenarios: Save scenarios (Simulation page)
  write:config: 'Change tenant configuration: flow rules, classification overrides, budget versions and templates, valuation refresh'
  write:data: 'Import rows from a spreadsheet Claude read (Excel in, 2026-10-29): cash forecasts, a GL version, a bank statement; preview first, then commit'
  run:build: 'Call the BUILD''s functions that only read (POST /api/v1/fn/<name>): the logic the account built, served as an API (2026-10-29)'
  run:build:write: 'Also call the BUILD''s functions that change data (declared "writes": true in its kphi.json)'
x-limits:
  per_ip_per_min: 200
  extension_per_min: 120
  extension_per_day: 20000