> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sure.am/llms.txt
> Use this file to discover all available pages before exploring further.

# Show cash flow and optional Sankey graph

> Server-calculated income, spending, savings, and daily cumulative comparison in family currency. Uses the authenticated user’s finance accounts and Sure reporting rules. Browser sessions do not authenticate this public API.



## OpenAPI

````yaml /openapi.yaml get /api/v1/cash_flow
openapi: 3.0.3
info:
  title: Sure API
  version: v1
  description: OpenAPI documentation generated from executable request specs.
servers:
  - url: https://app.sure.am
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
paths:
  /api/v1/cash_flow:
    get:
      tags:
        - Cash Flow
      summary: Show cash flow and optional Sankey graph
      description: >-
        Server-calculated income, spending, savings, and daily cumulative
        comparison in family currency. Uses the authenticated user’s finance
        accounts and Sure reporting rules. Browser sessions do not authenticate
        this public API.
      parameters:
        - name: month
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Non-future first day YYYY-MM-01; defaults to the current month in
            the family time zone.
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - sankey
          description: >-
            Append server-calculated graph to the monthly summary; cannot
            combine with view.
        - name: view
          in: query
          required: false
          schema:
            type: string
            enum:
              - sankey
          description: >-
            Graph-only envelope; omits daily comparison. Accepts month or an
            explicit date range; cannot combine with include.
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Inclusive ISO date. Requires end_date and view=sankey; cannot
            combine with month.
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Inclusive ISO date at or after start_date. Explicit ranges preserve
            their bounds, including future dates.
        - name: group_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - category
              - account
          description: >-
            How to group the Sankey graph. Requires view=sankey. "category"
            (default) routes flows through a single Cash Flow node; "account"
            routes them through each individual account.
      responses:
        '200':
          description: summary returned
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CashFlow'
                  - $ref: '#/components/schemas/CashFlowGraph'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: invalid query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKeyAuth: []
components:
  schemas:
    CashFlow:
      type: object
      required:
        - month
        - as_of
        - time_zone
        - currency
        - period
        - income
        - spending
        - net_savings
        - savings_rate
        - spending_comparison
      properties:
        month:
          type: string
          format: date
        as_of:
          type: string
          format: date
        time_zone:
          type: string
        currency:
          type: string
        period:
          $ref: '#/components/schemas/FinancialPeriod'
        income:
          type: string
        spending:
          type: string
        net_savings:
          type: string
        sankey:
          $ref: '#/components/schemas/CashFlowSankey'
        savings_rate:
          type: string
          nullable: true
          description: Percentage points; null when income is nonpositive. May be negative.
        spending_comparison:
          type: object
          required:
            - previous_period
            - current_total
            - comparison_total
            - comparison_end_date
            - delta
            - current
            - previous
          properties:
            previous_period:
              $ref: '#/components/schemas/FinancialPeriod'
            current_total:
              type: string
            comparison_total:
              type: string
            delta:
              type: string
            comparison_end_date:
              type: string
              format: date
            current:
              type: array
              items:
                $ref: '#/components/schemas/SpendingPoint'
            previous:
              type: array
              items:
                $ref: '#/components/schemas/SpendingPoint'
    CashFlowGraph:
      type: object
      required:
        - as_of
        - time_zone
        - currency
        - period
        - sankey
      properties:
        as_of:
          type: string
          format: date
        time_zone:
          type: string
        currency:
          type: string
        period:
          $ref: '#/components/schemas/FinancialPeriod'
        sankey:
          $ref: '#/components/schemas/CashFlowSankey'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        message:
          type: string
          nullable: true
        details:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
          nullable: true
        errors:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Validation error messages (alternative to details used by trades,
            valuations, etc.)
    FinancialPeriod:
      type: object
      required:
        - start_date
        - end_date
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
    CashFlowSankey:
      type: object
      required:
        - basis
        - income
        - spending
        - net_savings
        - nodes
        - links
      description: >-
        Refunds net within each category. Parent direct amounts exclude child
        totals before partitioning by direction. Graph income/spending may
        differ from gross monthly totals; net savings agrees. Decimal strings
        retain FX precision. Empty flow has empty nodes and links. When
        group_by=account the basis is net_by_account and nodes include
        account-kind nodes representing individual accounts between income and
        expense categories.
      properties:
        basis:
          type: string
          enum:
            - net_by_category
            - net_by_account
        income:
          type: string
        spending:
          type: string
        net_savings:
          type: string
        nodes:
          type: array
          items:
            type: object
            required:
              - id
              - name
              - kind
              - value
              - percentage
              - category_id
              - filter_value
              - color
            properties:
              id:
                type: string
                description: >-
                  Stable direction-prefixed category identifier or structural
                  identifier
              name:
                type: string
              kind:
                type: string
                enum:
                  - income
                  - expense
                  - cash_flow
                  - account
                  - surplus
                  - deficit
              value:
                type: string
                description: Nonnegative decimal in envelope currency
              percentage:
                type: string
                description: >-
                  Percentage of parent, or side total for root categories;
                  structural balancing nodes use central capacity
              category_id:
                type: string
                format: uuid
                nullable: true
              filter_value:
                type: string
                nullable: true
                description: >-
                  Web transaction category filter; null means no category
                  drill-down
              color:
                type: string
                nullable: true
                description: User category color; structural colors belong to the client
        links:
          type: array
          items:
            type: object
            required:
              - source
              - target
              - value
              - percentage
            properties:
              source:
                type: integer
                minimum: 0
                description: Zero-based nodes index
              target:
                type: integer
                minimum: 0
                description: Zero-based nodes index
              value:
                type: string
                description: Positive decimal in envelope currency
              percentage:
                type: string
    SpendingPoint:
      type: object
      required:
        - date
        - amount
      properties:
        date:
          type: string
          format: date
        amount:
          type: string
          description: Cumulative decimal amount in family currency
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: X-Api-Key
      in: header
      description: API key for authentication. Generate one from your account settings.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.