K-φ (K-Phi) Explain Cell API

openapi: 3.2.0
info:
  title: K-φ Explain Cell 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: Explain Cell
paths:
  /api/v1/explain_cell:
    get:
      operationId: get_explain_cell
      summary: 'What is behind one number: rules, balances, postings'
      x-audience: data
      description: 'What is behind one number of the forecast or the statements, deterministically, from K-φ''s calc graph: a forecast collections, payments or scheduled line opens to its cash-flow rules company by company; each rule to its opening balance, new invoices or purchases, closing balance and the cohorts it was collected or paid from, and the ledger postings behind the opening balance; a P&L or balance sheet total to the lines it adds up; an account line to its postings (P&L: fiscal year to date; balance sheet: cumulative). Every level says whether its parts add up to it (identity). Ask with line ("fc:collections", "fc:payments", "pl:", "bs:"), period (YYYY-MM, or YYYY-Www for a weekly forecast with grain "week"), version, and entity for one company. Postings are listed 500 at most, with their count and sum. Answers only when the calc graph is on for the account (error calc_graph_off otherwise); KPIs and ratios are not explained this way yet.'
      x-scope: read:gl
      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: line
        in: query
        required: false
        description: 'What the number is: fc:collections, fc:payments, fc:scheduledIn, fc:scheduledOut, pl:<key>, bs:<key> (keys as kphi_get_pl / kphi_get_balance_sheet return them, e.g. pl:4000, pl:_NI, bs:_TOTAL_ASSETS).'
        schema:
          type: string
      - name: period
        in: query
        required: false
        description: 'The period of the number: YYYY-MM; YYYY-Www for a weekly forecast; for a statement, the version''s month.'
        schema:
          type: string
      - name: version
        in: query
        required: false
        description: The ledger version the statements and forecast are computed on (kphi_list_versions). Omit for the latest.
        schema:
          type: string
      - name: entity
        in: query
        required: false
        description: One company's code, for its own figures in its own currency. Omit for the group.
        schema:
          type: string
      - name: grain
        in: query
        required: false
        description: The forecast grain (default month).
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: How many levels down (default 2).
        schema:
          type: integer
      tags:
      - Explain Cell
    post:
      operationId: post_explain_cell
      summary: 'What is behind one number: rules, balances, postings'
      x-audience: data
      description: 'What is behind one number of the forecast or the statements, deterministically, from K-φ''s calc graph: a forecast collections, payments or scheduled line opens to its cash-flow rules company by company; each rule to its opening balance, new invoices or purchases, closing balance and the cohorts it was collected or paid from, and the ledger postings behind the opening balance; a P&L or balance sheet total to the lines it adds up; an account line to its postings (P&L: fiscal year to date; balance sheet: cumulative). Every level says whether its parts add up to it (identity). Ask with line ("fc:collections", "fc:payments", "pl:", "bs:"), period (YYYY-MM, or YYYY-Www for a weekly forecast with grain "week"), version, and entity for one company. Postings are listed 500 at most, with their count and sum. Answers only when the calc graph is on for the account (error calc_graph_off otherwise); KPIs and ratios are not explained this way yet.'
      x-scope: read:gl
      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:
                line:
                  type: string
                  description: 'What the number is: fc:collections, fc:payments, fc:scheduledIn, fc:scheduledOut, pl:<key>, bs:<key> (keys as kphi_get_pl / kphi_get_balance_sheet return them, e.g. pl:4000, pl:_NI, bs:_TOTAL_ASSETS).'
                period:
                  type: string
                  description: 'The period of the number: YYYY-MM; YYYY-Www for a weekly forecast; for a statement, the version''s month.'
                version:
                  type: string
                  description: The ledger version the statements and forecast are computed on (kphi_list_versions). Omit for the latest.
                entity:
                  type: string
                  description: One company's code, for its own figures in its own currency. Omit for the group.
                grain:
                  type: string
                  enum:
                  - month
                  - week
                  - quarter
                  description: The forecast grain (default month).
                depth:
                  type: integer
                  minimum: 0
                  maximum: 6
                  description: How many levels down (default 2).
              required:
              - line
              - period
              additionalProperties: false
      tags:
      - Explain Cell
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