API Documentation

Access Angavu Intelligence data programmatically

Authentication

API Authentication

All API requests require a Bearer token. Contact hello@angavuintelligence.com to request access.

Requesting Access

API access is available for enterprise partners. Include the following in your request:

  • Company name and use case
  • Expected request volume
  • Data types needed

Using Your Token

curl -X GET https://api.angavu.com/v1/reports/user_123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Rate Limits

  • Standard: 100 requests/minute
  • Enterprise: Custom limits available
  • Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Endpoints

API Reference

Base URL: https://api.angavu.com/v1

POST /api/v1/sync

Sync transaction data from Msaidizi app. Used by the mobile app to upload anonymized business data.

Request Body

{
  "user_id": "usr_abc123",
  "transactions": [
    {
      "type": "sale",
      "amount": 1200,
      "currency": "KES",
      "category": "vegetables",
      "timestamp": "2026-07-28T14:30:00Z"
    }
  ],
  "sync_token": "sync_xyz789"
}

Response 200 OK

{
  "status": "synced",
  "transactions_accepted": 1,
  "new_sync_token": "sync_xyz790",
  "insights": {
    "daily_revenue": 4500,
    "daily_expenses": 2800,
    "profit": 1700
  }
}
GET /api/v1/reports/{user_id}

Get business intelligence reports for a specific user. Returns aggregated financial data and AI-generated insights.

Path Parameters

  • user_id (string, required) — The user identifier

Query Parameters

  • period (string) — daily | weekly | monthly (default: daily)
  • from (string) — ISO 8601 date
  • to (string) — ISO 8601 date

Response 200 OK

{
  "user_id": "usr_abc123",
  "period": "weekly",
  "revenue": { "total": 31500, "trend": "+12%" },
  "expenses": { "total": 19600, "trend": "-3%" },
  "profit": { "total": 11900, "margin": "37.8%" },
  "top_products": [
    { "name": "Tomatoes", "revenue": 8400 },
    { "name": "Onions", "revenue": 5200 }
  ],
  "ai_insights": [
    "Your tomato sales increased 23% this week.",
    "Consider buying onions in bulk — you sell 15kg/week."
  ]
}
GET /api/v1/intelligence/{buyer_type}

Access aggregated economic intelligence data. Available for FMCG companies, lenders, and government agencies.

Path Parameters

  • buyer_type (string, required) — fmcg | lender | government

Query Parameters

  • region (string) — Geographic region filter (e.g., ke-nairobi, ng-lagos)
  • category (string) — Product category filter
  • granularity (string) — daily | weekly | monthly

Response 200 OK

{
  "buyer_type": "fmcg",
  "region": "ke-nairobi",
  "data_freshness": "2026-07-28T00:00:00Z",
  "demand_signals": [
    { "product": "Cooking Oil", "demand_index": 87, "trend": "+5%" },
    { "product": "Rice", "demand_index": 72, "trend": "-2%" }
  ],
  "market_size_estimate": "KES 2.4B/month",
  "worker_count": 45000,
  "confidence": 0.85
}

All data is aggregated and anonymized. No individual user data is exposed.

GET /api/v1/health

Health check endpoint. No authentication required.

Response 200 OK

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 86400
}
Errors

Error Codes

All errors follow a consistent JSON format.

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try again in 60 seconds.",
    "status": 429
  }
}

Common Error Codes

  • 401 UNAUTHORIZED — Missing or invalid API token
  • 403 FORBIDDEN — Token valid but insufficient permissions
  • 404 NOT_FOUND — Resource does not exist
  • 422 VALIDATION_ERROR — Request body failed validation
  • 429 RATE_LIMIT_EXCEEDED — Too many requests
  • 500 INTERNAL_ERROR — Server error (contact support)
Code Examples

Quick Start

Python

import requests

API_TOKEN = "your_token_here"
BASE_URL = "https://api.angavu.com/v1"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Get weekly report
response = requests.get(
    f"{BASE_URL}/reports/usr_abc123",
    headers=headers,
    params={"period": "weekly"}
)
print(response.json())

JavaScript / Node.js

const API_TOKEN = 'your_token_here';
const BASE_URL = 'https://api.angavu.com/v1';

const response = await fetch(
  `${BASE_URL}/reports/usr_abc123?period=weekly`,
  {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    }
  }
);
const data = await response.json();
console.log(data);

Need API Access?

Contact us to get your API token and start integrating with Angavu Intelligence.

Contact for API Access →