openapi: 3.2.0
info:
  title: Cacheflow Accounts API
  version: 0.0.3
servers:
- url: https://api.getcacheflow.com
  description: 'Production. Calls are tenant-routed: send Host: <org-flow-domain>.api.getcacheflow.com (per github.com/getcacheflow/api-examples SETUP.md). Host no longer resolves as of 2026-08-13.'
- url: https://api.sandbox.getcacheflow.com
  description: Sandbox. Tenant-routed as <org-flow-domain>.api.sandbox.getcacheflow.com. Host no longer resolves as of 2026-08-13.
tags:
- name: Accounts
paths:
  /api/latest/data/accounts/plaid:
    post:
      tags:
      - Accounts
      summary: Create Plaid account
      operationId: createAccountsWithPlaid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountsWithPlaidRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
  /api/latest/data/accounts/external:
    post:
      tags:
      - Accounts
      summary: Create external account
      operationId: createExternal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /api/latest/data/accounts/{id}:
    get:
      tags:
      - Accounts
      summary: Get an account
      operationId: getAccount
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /api/latest/data/accounts/funding:
    get:
      tags:
      - Accounts
      summary: List funding accounts
      operationId: getFundingAccount
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /api/latest/data/accounts/plaid/init:
    post:
      tags:
      - Accounts
      summary: Create Plaid token for initialization
      operationId: initCreateAccountWithPlaid
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: string
  /api/latest/data/accounts:
    get:
      tags:
      - Accounts
      summary: List accounts
      operationId: listAccounts
      parameters:
      - name: filterBy
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
  /api/latest/data/accounts/{id}/ledger-items:
    post:
      tags:
      - Accounts
      summary: Create a ledger item
      operationId: createAccountLedgerItem
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountLedgerItemRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountLedgerItemResponse'
components:
  schemas:
    PlaidAccount:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        subtype:
          type: string
        mask:
          type: string
    CreateAccountsWithPlaidRequest:
      type: object
      properties:
        publicToken:
          type: string
        institutionName:
          type: string
        legalName:
          type: string
        authorizeAmount:
          type: integer
          format: int64
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/PlaidAccount'
    AccountLedgerItemResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - pending
          - in_progress
          - failed
          - posted
          - cancelled
          - declined
          - reversed
          - receiver_pending
          - receiver_posted
        reason:
          type: string
        amount:
          type: integer
          format: int64
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        name:
          type: string
        type:
          type: string
        streetAddress:
          type: string
        subAddress:
          type: string
        otherAddress:
          type: string
        city:
          type: string
        region:
          type: string
        regionIso:
          type: string
        postalCode:
          type: string
        country:
          type: string
        countryIso:
          type: string
        verifiedAt:
          type: string
          format: date-time
    AccountLedgerItemRequest:
      type: object
      properties:
        accountId:
          type: string
          format: uuid
        transferId:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - DEBIT
          - CREDIT
        amount:
          type: integer
          format: int64
    Account:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        address:
          $ref: '#/components/schemas/Address'
        institutionName:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - depository
          - credit
          - manual
          - external
        subtype:
          type: string
        mask:
          type: string
        legalName:
          type: string
        currency:
          type: string
        ownerType:
          type: string
        routingNumber:
          type: string
        accountNumber:
          type: string
        wireNumber:
          type: string
        expMonth:
          type: integer
          format: int32
        expYear:
          type: integer
          format: int32
        cvv:
          type: integer
          format: int32
        bic:
          type: string
        iban:
          type: string
        sortCode:
          type: string
        institutionNumber:
          type: string
        transitNumber:
          type: string
        verificationLink:
          type: string
        mandateId:
          type: string