Skip to main content
The Sure API provides programmatic access to your financial data, enabling you to build custom integrations, automate workflows, and extend the functionality of Sure.

​
Base URL

All API requests should be made to: 
https://your-domain.com/api/v1
Replace your-domain.com with your Sure instance URL.

​
Versioning

The API is versioned through the URL path. The current version is v1. All endpoints are prefixed with /api/v1/. Breaking changes will result in a new API version.

​
Authentication

The Sure API supports two authentication methods:
  • API Key Authentication (recommended for server-to-server integrations)
  • OAuth 2.0 (recommended for user-facing applications)
See the Authentication page for detailed setup instructions.

​
Rate Limiting

API requests are rate limited based on your API key tier. Rate limits are calculated on an hourly basis:
TierRequests per Hour
Standard100
Premium1,000
Enterprise10,000
Self-hosted instances have rate limiting disabled by default.

​
Rate Limit Headers

Every API response includes rate limit information in the headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 2847
  • X-RateLimit-Limit: Maximum requests allowed in the current window
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Seconds until the rate limit resets

​
Rate Limit Exceeded

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 2847 seconds.",
  "details": {
    "limit": 100,
    "current": 100,
    "reset_in_seconds": 2847
  }
}

​
Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

​
Successful Responses

Successful responses return data with a 2xx status code: 
{
  "id": "123",
  "name": "Grocery Store",
  "amount": 45.67,
  "date": "2024-03-04",
  "category": {
    "id": "456",
    "name": "Groceries"
  }
}

​
Pagination

List endpoints support pagination with the following query parameters:
​
page
integer
default:"1"
Page number to retrieve
​
per_page
integer
default:"25"
Number of items per page (1-100)
Paginated responses include metadata: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 150,
    "total_pages": 6,
    "next_page": 2,
    "prev_page": null
  }
}

​
Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

​
Status Codes

CodeDescription
200OK - Request succeeded
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Authentication failed or missing
403Forbidden - Insufficient permissions or scope
404Not Found - Resource not found
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error occurred

​
Error Response Format

Error responses follow a consistent structure: 
{
  "error": "error_code",
  "message": "Human-readable error message",
  "errors": ["Detailed error 1", "Detailed error 2"]
}

​
Common Error Codes

Authentication failed. Check that your API key or access token is valid and not expired.
{
  "error": "unauthorized",
  "message": "Access token or API key is invalid, expired, or missing"
}
Your authentication credentials don’t have the required permissions.
{
  "error": "insufficient_scope",
  "message": "This action requires the 'write' scope"
}
The requested resource doesn’t exist or you don’t have access to it.
{
  "error": "record_not_found",
  "message": "The requested resource was not found"
}
The request data failed validation. Check the errors array for details.
{
  "error": "validation_failed",
  "message": "Transaction could not be created",
  "errors": [
    "Account ID is required",
    "Amount must be a number"
  ]
}
Access denied to the requested resource (usually due to family-level access control).
{
  "error": "forbidden",
  "message": "Access denied to this resource"
}
Required parameters are missing or invalid.
{
  "error": "bad_request",
  "message": "Required parameters are missing or invalid"
}
The requested feature (e.g., AI) is not enabled for your account.
{
  "error": "feature_disabled",
  "message": "AI features are not enabled for this user"
}

​
Quick Start Example

Here’s a complete example of making an API request: 
curl https://your-domain.com/api/v1/accounts \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json"
With OAuth: 
curl https://your-domain.com/api/v1/accounts \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json"

​
Available Resources

The Sure API provides access to the following resources:

Accounts

List accounts and view balances

Transactions

Create, read, update, and delete transactions

Categories

Manage transaction categories

Merchants

View and manage merchants

Tags

Organize transactions with tags

Holdings

Access investment holdings data

Trades

Manage investment trades

Valuations

Create and update asset valuations

Imports

Import transactions from CSV

Sync

Trigger account synchronization

Chats

Interact with AI assistant

Usage

Monitor API usage statistics

​
User Management

Sure’s API also provides endpoints for managing your user account:

Reset Account

Reset all account data while keeping the user

Delete Account

Permanently delete your user account

​
Best Practices

1

Use API Keys for Server-to-Server

For backend integrations and scripts, use API key authentication. It’s simpler and more secure for non-interactive use cases.
2

Implement Exponential Backoff

When you hit rate limits or encounter server errors, implement exponential backoff before retrying.
3

Handle Errors Gracefully

Always check the error code in responses and handle different error types appropriately.
4

Use Pagination

For large datasets, use pagination parameters to limit response size and improve performance.
5

Secure Your Credentials

Never commit API keys or access tokens to version control. Use environment variables or secure credential storage.
6

Monitor Rate Limits

Check the X-RateLimit-* headers and implement logic to stay within your limits.

​
Support

For API support, please:
  • Check the API Reference for detailed endpoint documentation
  • Review the Authentication guide
  • Contact your instance administrator for self-hosted deployments

Build docs developers (and LLMs) love

Get started for freeTalk to us