Skip to main content
POST
/
api
/
ai
/
categorize
curl -X POST https://api.example.com/api/ai/categorize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "description": "MERCADONA SUPERMERCADOS",
        "date": "2026-03-05",
        "amount": -85.50
      },
      {
        "description": "REPSOL GASOLINERA",
        "date": "2026-03-04",
        "amount": -60.00
      },
      {
        "description": "TRANSFERENCIA NOMINA",
        "date": "2026-03-01",
        "amount": 2500.00
      }
    ]
  }'

{
  "success": true,
  "categories": [
    {
      "category": "alimentacion",
      "subcategory": "supermercados"
    },
    {
      "category": "transporte",
      "subcategory": "gasolina"
    },
    {
      "category": "ingresos",
      "subcategory": "nomina"
    }
  ],
  "responseTime": 1250
}

​
Overview

This endpoint uses AI to automatically assign categories and subcategories to financial transactions based on their descriptions. It supports multiple AI providers including Groq, Ollama, Claude, Gemini, and Hugging Face.
Categorization is free if done immediately after a parse request (within the same rate limit window). Otherwise, it counts toward your AI rate limit.

​
Authentication

This endpoint requires authentication via JWT token and CSRF protection.
​
Authorization
string
required
Bearer token for authentication
​
X-CSRF-Token
string
required
CSRF token for request validation

​
Request Body

​
transactions
array
required
Array of transaction objects to categorize. Each transaction must contain at least a description.

​
Response

​
success
boolean
required
Indicates if the request was successful
​
categories
array
required
Array of category assignments, one for each input transaction in the same order
​
responseTime
number
required
Time taken to process the request in milliseconds

​
Available Categories

The AI will assign one of the following categories:
  • ALIMENTACION: Supermarkets, grocery stores, food shopping
  • TRANSPORTE: Gas stations, public transport, taxi, Uber
  • RESTAURANTES: Restaurants, bars, cafes, fast food
  • SALUD: Pharmacy, doctor, hospitals, gym
  • HOGAR: Electricity, water, gas, internet, mobile phone
  • OCIO: Cinema, theater, concerts, travel, entertainment
  • VEHICULO: Car maintenance, insurance
  • ROPA: Clothing stores, shoe stores
  • INGRESOS: Salary, received transfers, income
  • TRANSFERENCIAS: Bizum, transfers between accounts
  • OTROS: Anything that doesn’t fit other categories

​
Supported AI Providers

This endpoint works with the following AI providers:
  • Groq - Fast inference with llama-3.3-70b-versatile
  • Ollama - Local AI with llama3:latest (requires local installation)
  • Claude - Anthropic’s claude-sonnet-4-20250514
  • Gemini - Google’s gemini-2.0-flash
  • Hugging Face - Qwen/Qwen2.5-72B-Instruct via router

​
Rate Limiting

This endpoint is subject to rate limiting:
  • Free when called immediately after /api/ai/parse
  • Otherwise counts as 1 request toward your AI rate limit
  • Check /api/ai/status for your current rate limit status

​
Security

All transaction descriptions are sanitized before processing to prevent prompt injection and other security issues. Malicious content will be blocked. 
curl -X POST https://api.example.com/api/ai/categorize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "description": "MERCADONA SUPERMERCADOS",
        "date": "2026-03-05",
        "amount": -85.50
      },
      {
        "description": "REPSOL GASOLINERA",
        "date": "2026-03-04",
        "amount": -60.00
      },
      {
        "description": "TRANSFERENCIA NOMINA",
        "date": "2026-03-01",
        "amount": 2500.00
      }
    ]
  }'

{
  "success": true,
  "categories": [
    {
      "category": "alimentacion",
      "subcategory": "supermercados"
    },
    {
      "category": "transporte",
      "subcategory": "gasolina"
    },
    {
      "category": "ingresos",
      "subcategory": "nomina"
    }
  ],
  "responseTime": 1250
}

​
Error Codes

Status CodeDescription
200Success - transactions categorized
400Bad request - invalid input or AI not available
401Unauthorized - missing or invalid token
403Forbidden - CSRF validation failed or security block
429Too many requests - rate limit exceeded
500Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us