K-φ (K-Phi) Sheets API

openapi: 3.2.0
info:
  title: K-φ Sheets 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: Sheets
paths:
  /api/v1/sheets:
    get:
      x-audience: data
      x-group: sheets
      operationId: sheets_list
      summary: 'The Google Sheets registered as inputs: tabs, columns, row counts, the path of…'
      x-scope: read:sheets
      security:
      - bearer: []
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
      tags:
      - Sheets
    post:
      x-audience: data
      x-group: sheets
      operationId: sheets_register
      summary: 'Register a Google Sheet: every tab (or those named) served as JSON'
      description: 'The sheet is shared "Anyone with the link" (Viewer), or with K-φ''s service address. Read only: K-φ never writes to it. Registering it again reads it again.'
      x-scope: write:sheets
      security:
      - bearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                name:
                  type: string
                tabs:
                  type: array
                  items:
                    type: string
                auto_sync:
                  type: boolean
                  description: Load the contract tabs into K-φ each time the sheet changes (needs write:data)
              required:
              - url
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
        '422':
          description: Not a sheets link, not shared, or unreadable
      tags:
      - Sheets
  /api/v1/sheets/{id}:
    get:
      x-audience: data
      x-group: sheets
      operationId: sheets_get
      summary: 'One registered sheet: its tabs, columns and last read'
      x-scope: read:sheets
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
        '404':
          description: No such sheet
      tags:
      - Sheets
    delete:
      x-audience: data
      x-group: sheets
      operationId: sheets_remove
      summary: Stop serving a sheet (the sheet itself is untouched)
      x-scope: write:sheets
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
      tags:
      - Sheets
  /api/v1/sheets/{id}/{tab}:
    get:
      x-audience: data
      x-group: sheets
      operationId: sheets_rows
      summary: 'The rows of a tab as JSON: row 1 is the header; numbers, dates and booleans…'
      description: 'since=: unchanged, { changed: false } and no rows. limit (default 1000, at most 10000) and offset page the rows. Read again from Google when the last read is over a minute old.'
      x-scope: read:sheets
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: tab
        in: path
        required: true
        schema:
          type: string
      - name: since
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
        '404':
          description: No such sheet or tab
      tags:
      - Sheets
  /api/v1/sheets/{id}/validate:
    post:
      x-audience: data
      x-group: sheets
      operationId: sheets_validate
      summary: Check the contract tabs (BAL, TRA, INV, MAP, FX…) row by row; nothing stored
      x-scope: read:sheets
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
        '404':
          description: No such sheet
      tags:
      - Sheets
  /api/v1/sheets/{id}/sync:
    post:
      x-audience: data
      x-group: sheets
      operationId: sheets_sync
      summary: 'Load the contract tabs into K-φ: all rows pass, or nothing is stored'
      description: 'Tabs named after a contract object (BAL, TRA, INV, MAP, FX; "TRA - Main bank" works) are checked against the ingest contract v1, then stored: bank balances and transactions, invoices, mappings, FX rates. One refused row and nothing is stored: the answer gives the tab, line and field. Webhooks: sync.done, sync.failed.'
      x-scope: write:data
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
        '404':
          description: No such sheet
        '422':
          description: No contract tab, or Google unreachable
      tags:
      - Sheets
  /api/v1/sheets/{id}/syncs:
    get:
      x-audience: data
      x-group: sheets
      operationId: sheets_syncs
      summary: 'The syncs of a sheet: done or failed, rows stored and refused, per tab'
      x-scope: read:sheets
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '401':
          description: No or invalid credential
        '403':
          description: Scope refused
        '404':
          description: No such sheet
      tags:
      - Sheets
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