API Documentation

This page covers the public transaction scoring API, authentication, response shape, bulk uploads, and common error handling. Use the dashboard API Hub for key generation and live testing.

Base URL

https://fraud-guard-ai-backend.onrender.com

Auth

X-API-Key: <your_api_key> Content-Type: application/json

Rate limits

Plan-based limits apply. Use batch scoring where possible to reduce request volume.

Single transaction scoring

POST a JSON payload to receive a fraud decision, score, and explanation.

curl -X POST "{BASE_URL}/api/v1/analyze"   -H "X-API-Key: <your_api_key>"   -H "Content-Type: application/json"   -d '{
    "amount": 199.99,
    "merchant": "electronics",
    "location": "Colombo, Sri Lanka",
    "time": "2026-04-09 10:30"
  }'

import requests

base_url = "{BASE_URL}"
payload = {
    "amount": 199.99,
    "merchant": "electronics",
    "location": "Colombo, Sri Lanka",
    "time": "2026-04-09 10:30",
}

response = requests.post(
    f"{base_url}/api/v1/analyze",
    headers={"X-API-Key": "<your_api_key>", "Content-Type": "application/json"},
    json=payload,
    timeout=15,
)
print(response.status_code)
print(response.json())

const response = await fetch("{BASE_URL}/api/v1/analyze", {
  method: "POST",
  headers: {
    "X-API-Key": "<your_api_key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 199.99,
    merchant: "electronics",
    location: "Colombo, Sri Lanka",
    time: "2026-04-09 10:30",
  }),
});

const data = await response.json();
console.log(data);

Bulk CSV upload

For Pro users, upload a CSV file to score multiple transactions in a single request.

curl -X POST "{BASE_URL}/api/v1/analyze/bulk-csv"   -H "X-API-Key: <your_api_key>"   -F "user_id=<user_id>"   -F "file=@transactions.csv;type=text/csv"

Response shape

{
  "transaction_id": "uuid",
  "status": "safe | risk",
  "risk_score": 0.0,
  "confidence": 0.0,
  "model_version": "string",
  "explanation": {
    "top_features": ["merchant", "amount", "location"]
  }
}

Common errors

401 - Missing or invalid API key.
403 - Plan does not allow the requested operation.
422 - Invalid or incomplete request payload.
500 - Unexpected server or model error.

Integration notes

Store the API key in environment variables, never in client-side source.
Use Clerk for dashboard authentication and Stripe for billing; both are separate from request signing.
For location-based scoring, send city or country strings such as Colombo, Sri Lanka or Negombo, Sri Lanka.
Keep request payloads small and consistent to reduce latency and improve model throughput.