AI2Fin

AI2Fin Smart Categories API

Category sets, multi-category assignments, and transaction history (Elite+ only)

GitHub OpenAPI

Operations 19

GET /api/category-sets List category sets #
POST /api/category-sets Create category set #
GET /api/category-sets/active Get active category set #
GET /api/category-sets/{id} Get category set by ID #
PUT /api/category-sets/{id} Update category set #
DELETE /api/category-sets/{id} Delete category set #
POST /api/category-sets/{id}/activate Activate category set #
POST /api/category-sets/{id}/duplicate Duplicate category set #
POST /api/category-sets/move-category Move category to set #
GET /api/category-sets/categories/from-sets Get categories from sets #
POST /api/transaction-categories/batch Get categories for multiple transactions #
GET /api/transaction-categories/{transactionId} Get transaction categories #
POST /api/transaction-categories/{transactionId} Assign category to transaction #
PUT /api/transaction-categories/{transactionId} Replace transaction categories #
POST /api/transaction-categories/{transactionId}/multiple Assign multiple categories #
DELETE /api/transaction-categories/{transactionId}/{categoryId} Remove category from transaction #
GET /api/transaction-history/{entityType}/{entityId} Get entity history #
GET /api/transaction-history/{entityType}/{entityId}/{fieldName} Get field history #
GET /api/transaction-history/recent Get recent changes #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/ai2fin-com/openapi/ai2fin-com-smart-categories-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/ai2fin-com/json-schema/ai2fin-com-transaction-field-history-schema.json
📊
JSONSchema
https://artifacts.apis.io/ai2fin-com/json-schema/ai2fin-com-category-set-schema.json
📊
JSONSchema
https://artifacts.apis.io/ai2fin-com/json-schema/ai2fin-com-custom-rule-input-schema.json
📊
JSONSchema
https://artifacts.apis.io/ai2fin-com/json-schema/ai2fin-com-transaction-category-schema.json
📊
JSONSchema
https://artifacts.apis.io/ai2fin-com/json-schema/ai2fin-com-bank-transaction-schema.json
📊
JSONSchema
https://artifacts.apis.io/ai2fin-com/json-schema/ai2fin-com-bill-pattern-input-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/ai2fin-com:ai2fin-com-smart-categories-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

ai2fin-com-smart-categories-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: AI2Fin Financial Management Smart Categories 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: Smart Categories
  description: Category sets, multi-category assignments, and transaction history (Elite+ only)
paths:
  /api/category-sets:
    get:
      tags:
      - Smart Categories
      summary: List category sets
      description: Get all category sets for the authenticated user. Elite+ subscription required.
      responses:
        '200':
          description: Category sets retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  sets:
                    type: array
                    items:
                      $ref: '#/components/schemas/CategorySet'
                  count:
                    type: integer
        '403':
          description: Elite+ subscription required
      operationId: getApiCategorySets
      x-operation-id-source: derived
    post:
      tags:
      - Smart Categories
      summary: Create category set
      description: Create a new category set. Elite+ subscription required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  example: Business Expenses
                description:
                  type: string
                  example: All business-related expense categories
                color:
                  type: string
                  example: '#3B82F6'
                icon:
                  type: string
                  example: Briefcase
      responses:
        '201':
          description: Category set created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  set:
                    $ref: '#/components/schemas/CategorySet'
                  message:
                    type: string
        '409':
          description: Category set with this name already exists
      operationId: postApiCategorySets
      x-operation-id-source: derived
  /api/category-sets/active:
    get:
      tags:
      - Smart Categories
      summary: Get active category set
      description: Get the currently active category set for the user.
      responses:
        '200':
          description: Active category set retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  set:
                    $ref: '#/components/schemas/CategorySet'
      operationId: getApiCategorySetsActive
      x-operation-id-source: derived
  /api/category-sets/{id}:
    get:
      tags:
      - Smart Categories
      summary: Get category set by ID
      description: Get a specific category set with its categories.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Category set retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  set:
                    $ref: '#/components/schemas/CategorySet'
        '404':
          description: Category set not found
      operationId: getApiCategorySetsById
      x-operation-id-source: derived
    put:
      tags:
      - Smart Categories
      summary: Update category set
      description: Update an existing category set.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                color:
                  type: string
                icon:
                  type: string
                isActive:
                  type: boolean
      responses:
        '200':
          description: Category set updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  set:
                    $ref: '#/components/schemas/CategorySet'
                  message:
                    type: string
        '404':
          description: Category set not found
      operationId: putApiCategorySetsById
      x-operation-id-source: derived
    delete:
      tags:
      - Smart Categories
      summary: Delete category set
      description: Delete a category set. Categories will be moved to the default set. Default sets cannot be deleted.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Category set deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  movedCategories:
                    type: integer
                  message:
                    type: string
        '400':
          description: Cannot delete default category set
        '404':
          description: Category set not found
      operationId: deleteApiCategorySetsById
      x-operation-id-source: derived
  /api/category-sets/{id}/activate:
    post:
      tags:
      - Smart Categories
      summary: Activate category set
      description: Set a category set as the active set for the user.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Category set activated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  previousActiveSetId:
                    type: string
                  newActiveSetId:
                    type: string
                  message:
                    type: string
        '404':
          description: Category set not found
      operationId: postApiCategorySetsByIdActivate
      x-operation-id-source: derived
  /api/category-sets/{id}/duplicate:
    post:
      tags:
      - Smart Categories
      summary: Duplicate category set
      description: Create a copy of a category set with all its categories.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  example: Business Expenses Copy
      responses:
        '201':
          description: Category set duplicated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  set:
                    $ref: '#/components/schemas/CategorySet'
                  message:
                    type: string
        '404':
          description: Category set not found
        '409':
          description: Category set with this name already exists
      operationId: postApiCategorySetsByIdDuplicate
      x-operation-id-source: derived
  /api/category-sets/move-category:
    post:
      tags:
      - Smart Categories
      summary: Move category to set
      description: Move a category from one set to another.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - categoryId
              - targetSetId
              properties:
                categoryId:
                  type: string
                targetSetId:
                  type: string
      responses:
        '200':
          description: Category moved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  category:
                    $ref: '#/components/schemas/Category'
                  message:
                    type: string
        '404':
          description: Category or target set not found
      operationId: postApiCategorySetsMoveCategory
      x-operation-id-source: derived
  /api/category-sets/categories/from-sets:
    get:
      tags:
      - Smart Categories
      summary: Get categories from sets
      description: Get categories from specific sets, grouped by set ID. Useful for dropdowns and filtering.
      parameters:
      - name: setIds
        in: query
        description: Comma-separated list of set IDs
        schema:
          type: string
      responses:
        '200':
          description: Categories retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  categories:
                    type: array
                    items:
                      $ref: '#/components/schemas/Category'
                  grouped:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/Category'
                  count:
                    type: integer
      operationId: getApiCategorySetsCategoriesFromSets
      x-operation-id-source: derived
  /api/transaction-categories/batch:
    post:
      tags:
      - Smart Categories
      summary: Get categories for multiple transactions
      description: Fetch category assignments for many transactions in a single request. Use this instead of calling GET /api/transaction-categories/{transactionId} once per transaction; it collapses what would be N requests into one. Accepts up to 500 transaction IDs per call. Unknown or not-yet-categorized IDs are returned with an empty array.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - transactionIds
              properties:
                transactionIds:
                  type: array
                  description: Transaction IDs to fetch categories for (maximum 500 per request).
                  items:
                    type: string
      responses:
        '200':
          description: Category assignments keyed by transaction ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  categories:
                    type: object
                    description: Map of transaction ID to its category assignments. Every requested ID is present; a transaction with no categories maps to an empty array.
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/TransactionCategory'
      operationId: postApiTransactionCategoriesBatch
      x-operation-id-source: derived
  /api/transaction-categories/{transactionId}:
    get:
      tags:
      - Smart Categories
      summary: Get transaction categories
      description: Get all categories assigned to a transaction.
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Categories retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  categories:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionCategory'
      operationId: getApiTransactionCategoriesByTransactionId
      x-operation-id-source: derived
    post:
      tags:
      - Smart Categories
      summary: Assign category to transaction
      description: Assign a category to a transaction. Transactions can have multiple categories.
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - categoryId
              properties:
                categoryId:
                  type: string
                categorySetId:
                  type: string
                isPrimary:
                  type: boolean
                  default: false
                confidence:
                  type: number
                  minimum: 0
                  maximum: 1
                assignedBy:
                  type: string
                  enum:
                  - user
                  - ai
                  - import
                  - rule
                  - bulk
                notes:
                  type: string
      responses:
        '200':
          description: Category assigned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  category:
                    $ref: '#/components/schemas/TransactionCategory'
      operationId: postApiTransactionCategoriesByTransactionId
      x-operation-id-source: derived
    put:
      tags:
      - Smart Categories
      summary: Replace transaction categories
      description: Replace all categories on a transaction with a new set of categories.
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - categories
              properties:
                categories:
                  type: array
                  items:
                    type: object
                    required:
                    - categoryId
                    properties:
                      categoryId:
                        type: string
                      categorySetId:
                        type: string
                      isPrimary:
                        type: boolean
                      confidence:
                        type: number
                      assignedBy:
                        type: string
      responses:
        '200':
          description: Categories replaced
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  categories:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionCategory'
      operationId: putApiTransactionCategoriesByTransactionId
      x-operation-id-source: derived
  /api/transaction-categories/{transactionId}/multiple:
    post:
      tags:
      - Smart Categories
      summary: Assign multiple categories
      description: Assign multiple categories to a transaction at once.
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - categories
              properties:
                categories:
                  type: array
                  items:
                    type: object
                    required:
                    - categoryId
                    properties:
                      categoryId:
                        type: string
                      categorySetId:
                        type: string
                      isPrimary:
                        type: boolean
                      confidence:
                        type: number
                      assignedBy:
                        type: string
      responses:
        '200':
          description: Categories assigned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  categories:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionCategory'
      operationId: postApiTransactionCategoriesByTransactionIdMultiple
      x-operation-id-source: derived
  /api/transaction-categories/{transactionId}/{categoryId}:
    delete:
      tags:
      - Smart Categories
      summary: Remove category from transaction
      description: Remove a specific category assignment from a transaction.
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
      - name: categoryId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Category removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
      operationId: deleteApiTransactionCategoriesByTransactionIdByCategoryId
      x-operation-id-source: derived
  /api/transaction-history/{entityType}/{entityId}:
    get:
      tags:
      - Smart Categories
      summary: Get entity history
      description: Get full change history for a transaction, expense, bill, or bill pattern.
      parameters:
      - name: entityType
        in: path
        required: true
        schema:
          type: string
          enum:
          - transaction
          - expense
          - bill
          - billPattern
      - name: entityId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: History retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  history:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionFieldHistory'
        '400':
          description: Invalid entity type
      operationId: getApiTransactionHistoryByEntityTypeByEntityId
      x-operation-id-source: derived
  /api/transaction-history/{entityType}/{entityId}/{fieldName}:
    get:
      tags:
      - Smart Categories
      summary: Get field history
      description: Get change history for a specific field of an entity. Maximum 11 changes are retained.
      parameters:
      - name: entityType
        in: path
        required: true
        schema:
          type: string
          enum:
          - transaction
          - expense
          - bill
          - billPattern
      - name: entityId
        in: path
        required: true
        schema:
          type: string
      - name: fieldName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Field history retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  fieldName:
                    type: string
                  changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionFieldHistory'
                  count:
                    type: integer
      operationId: getApiTransactionHistoryByEntityTypeByEntityIdByFieldName
      x-operation-id-source: derived
  /api/transaction-history/recent:
    get:
      tags:
      - Smart Categories
      summary: Get recent changes
      description: Get recent field changes for the authenticated user.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: entityType
        in: query
        schema:
          type: string
          enum:
          - transaction
          - expense
          - bill
          - billPattern
      - name: fieldName
        in: query
        schema:
          type: string
      - name: since
        in: query
        description: ISO date string
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Recent changes retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionFieldHistory'
                  count:
                    type: integer
      operationId: getApiTransactionHistoryRecent
      x-operation-id-source: derived
components:
  schemas:
    TransactionCategory:
      type: object
      description: A category assignment for a transaction. Transactions can have multiple categories from different sets.
      properties:
        id:
          type: string
        transactionId:
          type: string
        categoryId:
          type: string
        categorySetId:
          type: string
        userId:
          type: string
        isPrimary:
          type: boolean
          description: Whether this is the primary category for the transaction
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: AI confidence score for the assignment
        assignedBy:
          type: string
          enum:
          - user
          - ai
          - import
          - rule
          - bulk
          description: Source of the category assignment
        assignedAt:
          type: string
          format: date-time
        notes:
          type: string
        category:
          $ref: '#/components/schemas/Category'
    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
    TransactionFieldHistory:
      type: object
      description: A history entry tracking a field change on a transaction, expense, bill, or bill pattern. Maximum 11 entries per field.
      properties:
        id:
          type: string
        userId:
          type: string
        entityType:
          type: string
          enum:
          - transaction
          - expense
          - bill
          - billPattern
          description: Type of entity being tracked
        entityId:
          type: string
          description: ID of the entity
        fieldName:
          type: string
          description: Name of the field that was changed (e.g., categoryId, amount, description)
        oldValue:
          type: string
          description: Previous value (JSON string)
        newValue:
          type: string
          description: New value (JSON string)
        changeReason:
          type: string
          description: Optional reason for the change
        changedBy:
          type: string
          enum:
          - user
          - ai
          - rule
          - system
          - import
          - bulk
          description: Source of the change
        changeSource:
          type: string
          description: Additional context about the change source
        createdAt:
          type: string
          format: date-time
    CategorySet:
      type: object
      description: A category set for organizing categories into groups (e.g., Business Expenses, Tax Deductible, Personal). Elite+ feature.
      properties:
        id:
          type: string
        name:
          type: string
          example: Business Expenses
        description:
          type: string
          example: All business-related expense categories
        color:
          type: string
          example: '#3B82F6'
        icon:
          type: string
          example: Briefcase
        userId:
          type: string
        isDefault:
          type: boolean
          description: Whether this is the default category set (cannot be deleted)
        isActive:
          type: boolean
          description: Whether this is the currently active category set
        categoryCount:
          type: integer
          description: Number of categories in this set
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  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.'