K-φ (K-Phi) Contract Ingest API

openapi: 3.2.0
info:
  title: K-φ Contract Ingest 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: Contract Ingest
paths:
  /api/v1/contract_ingest:
    post:
      operationId: post_contract_ingest
      summary: Store rows through the ingest contract
      x-audience: data
      description: 'WRITE — store rows in K-φ through the ingest contract v1 (GET /api/public/contract/v1): BAL bank balances, TRA bank transactions, INV invoices, MAP mappings, FX rates, VAR the account''s own variables (any reference series: variable, date, key, value). Without commit the rows are only checked: the answer gives each refused row, its field and the reason, and what would be stored. With commit: true the rows that pass are stored and the others come back refused. Ids are the source system''s own: sending the same id again updates the row, never duplicates it. Send BAL for an account before its TRA. LOAN and PAY are checked, not stored yet. Up to 5000 rows per call.'
      x-scope: write:data
      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:
                object:
                  type: string
                  enum:
                  - BAL
                  - TRA
                  - INV
                  - MAP
                  - FX
                  - LOAN
                  - PAY
                  - VAR
                  description: Which contract object the rows are
                rows:
                  type: array
                  items:
                    type: object
                  description: Rows in the contract shape (see /api/public/contract/v1/<OBJECT>.schema.json)
                commit:
                  type: boolean
                  description: true to store; omitted or false only checks
              required:
              - object
              - rows
              additionalProperties: false
      tags:
      - Contract Ingest
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