journalize-dev Reports API

openapi: 3.2.0
info:
  title: journalize Reports API
  contact:
    name: Journalize
    email: hello@journalize.dev
  version: 0.1.0
tags:
- name: Reports
paths:
  /reports/balance-sheet:
    get:
      summary: Get Balance Sheet
      description: 'No query params — a balance sheet is a point-in-time snapshot of full

        history, not a period. reports.get_balance_sheet() may read from

        realized_balances_cache (§5: "often servable from cache") or recompute

        on a miss; either way this route settles at the same fixed price

        regardless of which path served the request — cache-hit vs. cache-miss

        cost difference is an internal optimization, not something exposed as a

        price difference (same "one fixed price per route" rule as everywhere

        else in payments.py).


        allow_free_read=True shares free_reports_remaining with the other

        three report-tier endpoints (export, income-statement, trial-balance)

        — one combined pool of 2, not 2 each. See

        auth.FREE_ALLOWANCE_COLUMNS.'
      operationId: get_balance_sheet_reports_balance_sheet_get
      parameters:
      - name: X-Public-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Public-Key
      - name: X-Nonce
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nonce
      - name: X-Timestamp
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Timestamp
      - name: X-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Signature
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceSheetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reports
  /reports/income-statement:
    get:
      summary: Get Income Statement
      description: 'Both since/until omitted -> whole history (reports._clamp_to_period

        fills the gap from the actual entry date range, never an arbitrary

        sentinel — see reports.py). Structural validation of the range itself

        (until not before since) happens via schemas.ReportPeriodQuery before

        any work runs, same pattern as journal.py''s list_directives route.'
      operationId: get_income_statement_reports_income_statement_get
      parameters:
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Since
      - name: until
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Until
      - name: X-Public-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Public-Key
      - name: X-Nonce
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nonce
      - name: X-Timestamp
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Timestamp
      - name: X-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Signature
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeStatementResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reports
  /reports/trial-balance:
    get:
      summary: Get Trial Balance
      description: 'Same cost shape and same clamp mechanism as income-statement — §6:

        "both are Beancount''s own report functions over the same

        booked/realized entries." Kept as its own route (not a query-param

        variant of income-statement) so it''s individually priced, audited, and

        listed as its own resource for x402 directory discovery, even though

        the underlying compute path in reports.py is structurally identical.'
      operationId: get_trial_balance_reports_trial_balance_get
      parameters:
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Since
      - name: until
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Until
      - name: X-Public-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Public-Key
      - name: X-Nonce
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nonce
      - name: X-Timestamp
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Timestamp
      - name: X-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Signature
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialBalanceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reports
components:
  schemas:
    IncomeStatementResponse:
      properties:
        accepted:
          type: boolean
          title: Accepted
        doc:
          anyOf:
          - items:
              $ref: '#/components/schemas/RealAccountEntry'
            type: array
          - type: 'null'
          title: Doc
        errors:
          items:
            type: string
          type: array
          title: Errors
        free_reports_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Free Reports Remaining
      type: object
      required:
      - accepted
      title: IncomeStatementResponse
    InventoryPosition:
      properties:
        number:
          type: string
          title: Number
        currency:
          type: string
          title: Currency
        cost:
          anyOf:
          - $ref: '#/components/schemas/Cost'
          - type: 'null'
      type: object
      required:
      - number
      - currency
      title: InventoryPosition
    BalanceSheetResponse:
      properties:
        accepted:
          type: boolean
          title: Accepted
        doc:
          anyOf:
          - items:
              $ref: '#/components/schemas/RealAccountEntry'
            type: array
          - type: 'null'
          title: Doc
        errors:
          items:
            type: string
          type: array
          title: Errors
        free_reports_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Free Reports Remaining
      type: object
      required:
      - accepted
      title: BalanceSheetResponse
      description: 'Mirrors reports.ReportResult for GET /reports/balance-sheet.

        accepted=True with a non-empty errors list is a valid, billable

        response (§7) — e.g. missing price directives — not a failure.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Cost:
      properties:
        number:
          type: string
          title: Number
        currency:
          type: string
          title: Currency
        date:
          anyOf:
          - type: string
          - type: 'null'
          title: Date
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      type: object
      required:
      - number
      - currency
      title: Cost
    TrialBalanceResponse:
      properties:
        accepted:
          type: boolean
          title: Accepted
        doc:
          anyOf:
          - items:
              $ref: '#/components/schemas/RealAccountEntry'
            type: array
          - type: 'null'
          title: Doc
        errors:
          items:
            type: string
          type: array
          title: Errors
        free_reports_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Free Reports Remaining
      type: object
      required:
      - accepted
      title: TrialBalanceResponse
    RealAccountEntry:
      properties:
        account:
          type: string
          title: Account
        parent:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent
        balance:
          items:
            $ref: '#/components/schemas/InventoryPosition'
          type: array
          title: Balance
      type: object
      required:
      - account
      title: RealAccountEntry
      description: 'One entry in the flat adjacency list reports._serialize_real_account()

        now emits — was a recursive nested tree (RealAccountNode, containing a

        dict of RealAccountNode) until a real, confirmed problem: that shape

        requires a genuinely self-referential OpenAPI schema, which x402scan''s

        own API scanner (reading /openapi.json as its primary source) choked

        on with "Maximum call stack size exceeded" — confirmed directly, not

        guessed: a naive "fully substitute every $ref" resolver hits actual

        unbounded recursion against a self-referential schema, since there''s

        no way to inline a genuine cycle into a finite structure.


        `parent` is the immediate parent''s full account name (None for a

        top-level account like "Assets" or "Expenses") — an explicit

        adjacency-list pointer, even though it''s technically redundant with

        `account` itself (Beancount account names are colon-separated paths,

        so the parent is always "drop the last segment"). Included anyway so

        a consumer doesn''t have to parse that convention themselves just to

        reconstruct the tree.


        `number` fields inside `balance` stay strings end-to-end (see module

        docstring) — never re-parsed into a JSON float anywhere on the

        response path.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError