API Reference - FAII Documentation

The FAII API provides RESTful endpoints for integrating search and AI intelligence monitoring directly into your applications, tools, and workflows.

Base URL

All API requests should be made to:

https://app.faii.ai/api

Note: For development and testing, you can use the local FAII backend API at http://127.0.0.1:8080/api

Authentication

FAII uses Bearer token authentication. Include your API token in the Authorization header of all requests:

curl https://app.faii.ai/api/supabase/dashboards \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Getting Your API Token

Log into your FAII dashboard at app.faii.ai

Navigate to Settings

Click Settings → Integrations → API

Generate Token

Click “Create API Token” and copy the generated token

Store Securely

Store your token securely in your application (environment variables recommended)

Keep your API tokens secure! Never commit them to public repositories or share them publicly. Tokens provide full access to your FAII data.

API Architecture

Core Endpoints

The FAII API is organized around RESTful resources:

Campaigns - Create and manage monitoring campaigns
Intelligence Data - Access SERP and Chat intelligence results
Analytics - Historical data and trend analysis
Alerts - Configure and manage notification settings

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully"
}

Error responses include error details:

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided API token is invalid or expired"
  }
}

Quick Start

Basic Usage Examples

JavaScript/Node.js
Python
PHP
cURL

// Using fetch (Node.js 18+)
const response = await fetch('https://app.faii.ai/api/supabase/dashboards', {
  headers: {
    'Authorization': `Bearer ${process.env.FAII_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

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

import requests

headers = {
    'Authorization': f'Bearer {os.environ["FAII_API_TOKEN"]}',
    'Content-Type': 'application/json'
}

response = requests.get('https://app.faii.ai/api/supabase/dashboards', headers=headers)
data = response.json()

print(data['data'])

<?php
$headers = [
    'Authorization: Bearer ' . getenv('FAII_API_TOKEN'),
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.faii.ai/api/supabase/dashboards');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo $data['data'];

export FAII_API_TOKEN="your_api_token_here"

curl https://app.faii.ai/api/supabase/dashboards \
  -H "Authorization: Bearer $FAII_API_TOKEN" \
  -H "Content-Type: application/json"

Your First API Call

// List your campaigns
const campaigns = await faii.campaigns.list();

console.log(`You have ${campaigns.length} campaigns`);

Core Resources

Campaigns

Create and manage monitoring campaigns

Rankings

Access SERP ranking data

Mentions

Get AI platform mention data

Reports

Generate and export reports

Common Operations

Create a Campaign

const campaign = await faii.campaigns.create({
  name: 'Brand Monitoring',
  type: 'serp',
  keywords: ['your brand', 'your product'],
  frequency: 'daily',
  settings: {
    location: 'United States',
    device: 'desktop',
    search_engine: 'google'
  }
});

console.log(`Created campaign: ${campaign.id}`);

Get Ranking Data

const rankings = await faii.rankings.get({
  campaign_id: 'camp_123',
  start_date: '2025-10-01',
  end_date: '2025-10-18',
  keywords: ['specific keyword'] // optional filter
});

rankings.forEach(rank => {
  console.log(`${rank.keyword}: Position ${rank.position}`);
});

Monitor AI Mentions

const mentions = await faii.mentions.get({
  brand: 'YourBrand',
  platforms: ['chatgpt', 'claude', 'perplexity'],
  start_date: '2025-10-01'
});

console.log(`Found ${mentions.length} mentions`);

Generate a Report

const report = await faii.reports.create({
  campaign_id: 'camp_123',
  format: 'pdf',
  date_range: 'last_30_days',
  include: ['rankings', 'competitors', 'trends']
});

console.log(`Report URL: ${report.download_url}`);

Response Format

All API responses follow this structure:

{
  "success": true,
  "data": {
    // Resource data here
  },
  "meta": {
    "timestamp": "2025-10-18T10:00:00Z",
    "version": "1.0"
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Campaign ID is required",
    "details": {}
  }
}

Rate Limits

Plan	Requests/Hour	Requests/Day
Starter	100	1,000
Professional	1,000	10,000
Enterprise	10,000	100,000

Rate limit info is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1634567890

Webhooks

Receive real-time notifications when events occur:

// Configure webhook endpoint
await faii.webhooks.create({
  url: 'https://your-app.com/webhooks/faii',
  events: [
    'campaign.completed',
    'ranking.changed',
    'mention.detected'
  ],
  secret: 'your_webhook_secret'
});

Learn more about webhooks →

Error Codes

Code	Description
`invalid_request`	Request is malformed or missing required fields
`authentication_failed`	API key is invalid or missing
`not_found`	Requested resource doesn’t exist
`rate_limit_exceeded`	You’ve hit your rate limit
`server_error`	Something went wrong on our end

Best Practices

Pro Tip: Use webhooks instead of polling for real-time data. It’s faster, more efficient, and counts less towards your rate limit.

Performance Optimization

Cache responses when possible
Use pagination for large result sets
Filter requests to only get needed data
Batch operations when creating multiple resources
Use webhooks instead of polling

Security

Never expose API keys in client-side code
Use environment variables for API keys
Rotate keys regularly (every 90 days)
Implement webhook signature verification
Use HTTPS for all webhook endpoints

Error Handling

try {
  const campaign = await faii.campaigns.get('camp_123');
} catch (error) {
  if (error.code === 'not_found') {
    console.log('Campaign not found');
  } else if (error.code === 'rate_limit_exceeded') {
    // Wait and retry
    await sleep(60000);
    return retryRequest();
  } else {
    // Log and alert
    logger.error('FAII API Error:', error);
  }
}

SDKs & Libraries

Official SDKs available for:

JavaScript/TypeScript - @faii/sdk
Python - faii-python
PHP - faii/sdk

Community libraries:

Ruby - faii-ruby
Go - go-faii

API Endpoints

Core FAII Endpoints

Campaign Management:

GET /api/campaigns - List all campaigns
POST /api/campaigns - Create a new campaign
GET /api/campaigns/{id} - Get campaign details
PUT /api/campaigns/{id} - Update campaign
DELETE /api/campaigns/{id} - Delete campaign

Intelligence Data:

GET /api/supabase/dashboards - Get dashboard data
GET /api/supabase/dashboards/intelligence-overview - Get intelligence overview
GET /api/serp/rankings - Get SERP ranking data
GET /api/chat/mentions - Get Chat Intelligence mentions

Analytics & Reporting:

GET /api/analytics/campaign/{id} - Get campaign analytics
GET /api/reports/generate - Generate reports
GET /api/export/csv - Export data as CSV

Authentication Endpoints

POST /api/auth/login - User authentication
POST /api/auth/logout - User logout
GET /api/auth/me - Get current user info

Example API Calls

Get Dashboard Data
Get Campaign Rankings
Get AI Mentions

curl https://app.faii.ai/api/supabase/dashboards \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl https://app.faii.ai/api/serp/rankings?campaign_id=camp_123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl https://app.faii.ai/api/chat/mentions?brand=YourBrand \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Support

Need help with the API?

📧 [email protected]
📚 Full API Documentation
💬 Developer community (coming soon)
🐛 Report issues

Changelog

Stay updated with API changes:

v1.2.0 (2025-10-15): Added Chat Intelligence endpoints
v1.1.0 (2025-09-01): Webhook support added
v1.0.0 (2025-08-01): Initial API release

View full changelog →

API Documentation

​Base URL

​Authentication

​Getting Your API Token

​API Architecture

​Core Endpoints

​Response Format

​Quick Start

​Basic Usage Examples

​Your First API Call

​Core Resources

Campaigns

Rankings

Mentions

Reports

​Common Operations

​Create a Campaign

​Get Ranking Data

​Monitor AI Mentions

​Generate a Report

​Response Format

​Error Responses

​Rate Limits

​Webhooks

​Error Codes

​Best Practices

​Performance Optimization

​Security

​Error Handling

​SDKs & Libraries

​API Endpoints

​Core FAII Endpoints

​Authentication Endpoints

​Example API Calls

​Support

​Changelog

Base URL

Authentication

Getting Your API Token

API Architecture

Core Endpoints

Response Format

Quick Start

Basic Usage Examples

Your First API Call

Core Resources

Common Operations

Create a Campaign

Get Ranking Data

Monitor AI Mentions

Generate a Report

Response Format

Error Responses

Rate Limits

Webhooks

Error Codes

Best Practices

Performance Optimization

Security

Error Handling

SDKs & Libraries

API Endpoints

Core FAII Endpoints

Authentication Endpoints

Example API Calls

Support

Changelog