AI2Fin Bank Transactions API

openapi: 3.2.0
info:
  title: AI2Fin Financial Management Bank Transactions API
  description: Financial management platform with AI-powered categorization, tax optimization, and bill management.
  version: 1.0.0
  contact:
    name: AI2Fin Support
    url: https://ai2fin.com
  license:
    name: Proprietary
servers:
- url: https://api.ai2fin.com
  description: Production
- url: http://localhost:3001
  description: Local Development
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: Bank Transactions
  description: First-party endpoints for managing your own transactions and CSV imports. These return your own account data in your own authenticated session; they are not a third-party integration surface. Data synced from connected bank feeds (open-banking / CDR data) stays within your account and is only ever returned to you.
paths:
  /api/bank/transactions:
    get:
      tags:
      - Bank Transactions
      summary: List your bank transactions
      description: 'Retrieve a paginated list of your own transactions, with filtering options. This is a first-party endpoint: it returns only the transactions belonging to your authenticated account, using your own session (bearer token or session cookie). Data from connected bank feeds (open-banking / CDR data) is your own data and is returned only to you here — this endpoint is not a third-party or server-to-server integration channel, and API keys are not accepted on it. To let an assistant work with your data, see the MCP endpoint; to send your own entries out to other tools, see webhooks and the Integration API.'
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: category
        in: query
        schema:
          type: string
        description: Filter by category ID
      - name: fromDate
        in: query
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        schema:
          type: string
          format: date
      - name: type
        in: query
        schema:
          type: string
          enum:
          - debit
          - credit
      responses:
        '200':
          description: Transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/BankTransaction'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
      operationId: getApiBankTransactions
      x-operation-id-source: derived
    post:
      tags:
      - Bank Transactions
      summary: Create bank transaction
      description: Manually add a new bank transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankTransactionInput'
      responses:
        '201':
          description: Transaction created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    $ref: '#/components/schemas/BankTransaction'
      operationId: postApiBankTransactions
      x-operation-id-source: derived
  /api/bank/transactions/{id}:
    get:
      tags:
      - Bank Transactions
      summary: Get transaction by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Transaction retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'
        '404':
          description: Transaction not found
      operationId: getApiBankTransactionsById
      x-operation-id-source: derived
    put:
      tags:
      - Bank Transactions
      summary: Update transaction
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankTransactionInput'
      responses:
        '200':
          description: Transaction updated successfully
      operationId: putApiBankTransactionsById
      x-operation-id-source: derived
    delete:
      tags:
      - Bank Transactions
      summary: Delete transaction
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Transaction deleted successfully
      operationId: deleteApiBankTransactionsById
      x-operation-id-source: derived
  /api/bank/upload:
    post:
      tags:
      - Bank Transactions
      summary: Upload bank statement CSV
      description: Upload and parse bank statement CSV file with intelligent categorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                categoryMappings:
                  type: string
                  description: JSON string of category mappings
      responses:
        '200':
          description: CSV processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionsImported:
                    type: integer
                  duplicatesSkipped:
                    type: integer
                  errors:
                    type: array
                    items:
                      type: string
      operationId: postApiBankUpload
      x-operation-id-source: derived
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        icon:
          type: string
        color:
          type: string
        isTaxDeductible:
          type: boolean
        taxCategory:
          type: string
        defaultGstRate:
          type: number
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        pages:
          type: integer
    BankTransactionInput:
      type: object
      required:
      - date
      - description
      - amount
      - type
      properties:
        date:
          type: string
          format: date-time
        description:
          type: string
        amount:
          type: number
        type:
          type: string
          enum:
          - debit
          - credit
        categoryId:
          type: string
        merchant:
          type: string
        gstAmount:
          type: number
        gstRate:
          type: number
        gstIncluded:
          type: boolean
    BankTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        date:
          type: string
          format: date-time
        description:
          type: string
        amount:
          type: number
          format: decimal
        type:
          type: string
          enum:
          - debit
          - credit
        categoryId:
          type: string
          format: uuid
        category:
          $ref: '#/components/schemas/Category'
        merchant:
          type: string
        isTaxDeductible:
          type: boolean
        businessUsePercentage:
          type: number
          minimum: 0
          maximum: 100
        gstAmount:
          type: number
        gstRate:
          type: number
        gstIncluded:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: First-party access token for your own signed-in session, obtained from the /api/enterprise-auth/login endpoint. The REST API returns your own account data to you — it is a first-party consumer surface, not a third-party integration channel. Data from connected bank feeds (open-banking / CDR data) is your own data, returned only to you in your own authenticated session.
    cookieAuth:
      type: apiKey
      in: cookie
      name: ai2_sess
      description: Session cookie for web applications
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key for the MCP Inspector endpoint (/mcp/inspector) only. Generate your own key via /api/api-keys. Format: mcp_<64 hex characters>. API keys carry mcp:* scopes and authenticate MCP Inspector operations — they are not accepted on the REST API (/api/...) or the main MCP endpoint (/mcp), which use OAuth bearer tokens.'