Refinal.ai

API Documentation

Integrate Refinal.ai into your applications with our REST API

Overview

The Refinal.ai API provides programmatic access to your financial data. You can retrieve transactions, manage tags, run analytics queries, and more.

Base URL

https://api.refinal.ai/v1

Rate Limits

  • • Standard plans: 100 requests/minute
  • • Pro plans: 500 requests/minute
  • • Enterprise plans: Custom limits

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header.

Getting your API Key

Generate an API key from your dashboard at Settings → API Keys. Keep your API key secure and never expose it in client-side code.

Example Request

curl -X GET "https://api.refinal.ai/v1/transactions" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Security Note: Never share your API key or commit it to version control. Use environment variables to store sensitive credentials.

Endpoints

Transactions

GET/api/v1/transactions

List all transactions with optional filtering

Parameters

NameTypeDescription
pageintegerPage number (default: 1)
limitintegerItems per page (default: 50, max: 200)
start_datestringFilter from date (ISO 8601)
end_datestringFilter to date (ISO 8601)
sourcestringFilter by source (stripe, revolut, coingate)
min_amountnumberMinimum transaction amount
max_amountnumberMaximum transaction amount
tagsstringComma-separated tag IDs
searchstringSearch in description
GET/api/v1/transactions/:id

Get a single transaction by ID

PATCH/api/v1/transactions/:id

Update transaction (tags, notes, category)

POST/api/v1/transactions/bulk-tag

Apply tags to multiple transactions

Tags

GET/api/v1/tags

List all tags

POST/api/v1/tags

Create a new tag

PATCH/api/v1/tags/:id

Update a tag

DELETE/api/v1/tags/:id

Delete a tag

Analytics

GET/api/v1/analytics/summary

Get summary statistics for a date range

Parameters

NameTypeDescription
start_datestringStart date (required)
end_datestringEnd date (required)
group_bystringGroup by: day, week, month, year
GET/api/v1/analytics/breakdown

Get breakdown by category, tag, or source

Parameters

NameTypeDescription
start_datestringStart date (required)
end_datestringEnd date (required)
dimensionstringDimension: category, tag, source, merchant
POST/api/v1/analytics/query

Run a custom analytics query

GET/api/v1/analytics/projections

Get AI-powered financial projections

Data Sources

GET/api/v1/sources

List connected data sources

POST/api/v1/sources/:provider/sync

Trigger a manual sync for a data source

GET/api/v1/sources/:provider/status

Get sync status for a data source

Example Response

{
  "data": [
    {
      "id": "txn_abc123",
      "amount": 1500.00,
      "currency": "USD",
      "description": "Stripe payout",
      "source": "stripe",
      "date": "2025-12-15T10:30:00Z",
      "tags": ["revenue", "recurring"],
      "category": "income"
    }
  ],
  "meta": {
    "total": 1543,
    "page": 1,
    "limit": 50,
    "total_pages": 31
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a message explaining what went wrong.

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'start_date' parameter must be a valid ISO 8601 date",
    "param": "start_date"
  }
}

HTTP Status Codes

CodeNameDescription
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error, please retry

SDKs & Libraries

We provide official SDKs to make integration easier:

Python

pip install refinal

Node.js

npm install @refinal/sdk

Ruby

gem install refinal

Need Help?

Have questions about the API? Our developer support team is here to help.

Contact API Support