Skip to main content

​
Introduction

The AdRecon API provides serverless endpoints for media proxying, page capture, user management, and payment integration. All endpoints are hosted on Vercel and interact with Supabase for authentication and data persistence.

​
Base URL

All API endpoints are relative to your deployment domain: 
https://your-domain.vercel.app/api

​
Authentication

Most endpoints require authentication using Supabase access tokens via the Authorization header: 
Authorization: Bearer <supabase_access_token>

​
Getting an Access Token

Tokens are obtained through Supabase Auth: 
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

// Sign in with email magic link
const { data, error } = await supabase.auth.signInWithOtp({
  email: '[email protected]',
  options: {
    emailRedirectTo: `${window.location.origin}/app`,
    shouldCreateUser: false
  }
})

// Get session token
const { data: { session } } = await supabase.auth.getSession()
const token = session?.access_token

​
Admin Access

Certain endpoints require admin privileges. Admin users are identified by: 
{
  "app_metadata": {
    "user_type": "admin"
  }
}
Non-admin users receive 403 Forbidden when accessing admin endpoints.

​
Error Handling

All error responses follow a consistent JSON structure: 
{
  "error": "Descriptive error message"
}

​
Common HTTP Status Codes

StatusMeaningCommon Causes
400Bad RequestMissing required parameters, invalid URL format
401UnauthorizedMissing or invalid bearer token
403ForbiddenValid auth but insufficient permissions (non-admin)
405Method Not AllowedWrong HTTP method (check Allow header)
415Unsupported Media TypeContent-Type mismatch for media proxy
429Too Many RequestsRate limit exceeded (includes Retry-After header)
500Internal Server ErrorUnexpected server-side failure
502Bad GatewayUpstream service failure
504Gateway TimeoutRequest exceeded timeout limits

​
Rate Limiting

Endpoints that perform expensive operations enforce rate limits:
  • Page Ripper: 10 captures per user per 15-minute window
  • Rate-limited responses include a Retry-After header (seconds until reset)
When a rate limit is exceeded, the API returns 429 with a Retry-After header. Respect this value to avoid further throttling.

​
CORS and Security

​
CORS Support

All endpoints support OPTIONS preflight requests and include appropriate CORS headers for browser-based clients.

​
SSRF Protection

Endpoints that fetch external URLs implement multiple layers of SSRF protection:
  1. Host allowlists — Only whitelisted domains accepted
  2. IP blocklists — Private/internal IP ranges rejected
  3. DNS resolution checks — Prevents DNS rebinding attacks
  4. Post-redirect validation — Final URL re-checked after redirects

​
Content Types

​
Request Content-Type

Most POST endpoints expect JSON: 
Content-Type: application/json

​
Response Content-Type

  • JSON endpoints: application/json
  • Media proxy: image/*, video/*, etc. (pass-through from upstream)
  • Page Ripper: application/zip

​
Caching

​
Media Proxy Caching

The /api/ad-media endpoint passes through upstream Cache-Control headers. When upstream omits caching directives, fallback policies apply:
  • Images: public, max-age=1800, s-maxage=21600 (30 min / 6 hours)
  • Videos: public, max-age=600, s-maxage=3600 (10 min / 1 hour)

​
Admin Endpoints

All admin endpoints return: 
Cache-Control: no-store
Never cache admin API responses.

​
Supported Authentication Methods

Email Magic Link

Passwordless login via one-time email link

Google OAuth

Social authentication with Google accounts

​
Environment Variables

Server-side endpoints reference these variables:
VariablePurposeRequired
SUPABASE_URLSupabase project URLYes
SUPABASE_SERVICE_ROLE_KEYServer-side auth keyYes (admin endpoints)
FANBASIS_API_KEYFanbasis integration keyNo (payment features only)

​
Next Steps

Media Proxy

Proxy Facebook/Instagram media assets

Page Ripper

Capture landing pages as ZIP archives

Admin Users

Manage user accounts and permissions

Fanbasis Integration

Payment webhooks and offer management

Build docs developers (and LLMs) love

Get started for freeTalk to us