K-φ (K-Phi) Query Gl API

openapi: 3.2.0
info:
  title: K-φ Query Gl 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: Query Gl
paths:
  /api/v1/query_gl:
    get:
      operationId: get_query_gl
      summary: Ledger entries, filtered by version, period, entity, account
      x-audience: data
      description: 'Query raw general-ledger entries with filters: version, period, entity, business unit, account prefix (e.g. "411" for all AR accounts under French PCG), and free-text search on the entry description. Returns matching rows (capped by limit, default 100, max 500) plus aggregates (total count, sum of debits and credits) computed over ALL matches, not just the returned page.'
      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: version
        in: query
        required: false
        description: 'GL version label (e.g. "2026-06"), from kphi_list_versions. Required when more than one version exists: without it the tool answers needs_version with the list instead of picking one.'
        schema:
          type: string
      - name: period
        in: query
        required: false
        description: Filter to a single period (YYYY-MM). Omit to include all periods in the version.
        schema:
          type: string
      - name: entity
        in: query
        required: false
        description: Filter to a single entity code. Omit for consolidated view across all entities.
        schema:
          type: string
      - name: bu
        in: query
        required: false
        description: Filter to a single business unit. Omit for all BUs.
        schema:
          type: string
      - name: acct_prefix
        in: query
        required: false
        description: Account number prefix filter, e.g. "411" or "70".
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Case-insensitive substring match on the entry description.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Max rows to return (default 100, max 500).
        schema:
          type: integer
      tags:
      - Query Gl
    post:
      operationId: post_query_gl
      summary: Ledger entries, filtered by version, period, entity, account
      x-audience: data
      description: 'Query raw general-ledger entries with filters: version, period, entity, business unit, account prefix (e.g. "411" for all AR accounts under French PCG), and free-text search on the entry description. Returns matching rows (capped by limit, default 100, max 500) plus aggregates (total count, sum of debits and credits) computed over ALL matches, not just the returned page.'
      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:
                version:
                  type: string
                  description: 'GL version label (e.g. "2026-06"), from kphi_list_versions. Required when more than one version exists: without it the tool answers needs_version with the list instead of picking one.'
                period:
                  type: string
                  description: Filter to a single period (YYYY-MM). Omit to include all periods in the version.
                entity:
                  type: string
                  description: Filter to a single entity code. Omit for consolidated view across all entities.
                bu:
                  type: string
                  description: Filter to a single business unit. Omit for all BUs.
                acct_prefix:
                  type: string
                  description: Account number prefix filter, e.g. "411" or "70".
                search:
                  type: string
                  description: Case-insensitive substring match on the entry description.
                limit:
                  type: integer
                  description: Max rows to return (default 100, max 500).
              additionalProperties: false
      tags:
      - Query Gl
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