API Reference

Complete reference for the Flipz REST API. Access your scraped data programmatically.

Base URL: https://your-domain.com/api/

Authentication

The Flipz API uses session-based authentication. You must be logged in to access API endpoints.

Session Authentication

All API requests require a valid session cookie. Login through the web interface first.

POST /auth/login
Content-Type: application/x-www-form-urlencoded

username=your_username&password=your_password&csrf_token=token

CSRF Protection

All POST requests require a valid CSRF token. Include the token in your request headers or form data.

Security: Always include CSRF tokens in POST requests to prevent cross-site request forgery attacks.

Products API

GET /api/products

Retrieve scraped products with filtering and pagination

Parameters

Parameter	Type	Description	Default
`page`	integer	Page number for pagination	1
`per_page`	integer	Items per page (max 100)	48
`search`	string	Search term for title/location	-
`session_id`	integer	Filter by scraping session	-

Example Request

GET /api/products?page=1&per_page=10&search=iphone&session_id=18

Example Response

{
  "products": [
    {
      "id": 1234,
      "title": "iPhone 13 Pro Max 256GB",
      "price": "£650",
      "location": "London",
      "url": "https://www.facebook.com/marketplace/item/...",
      "image": "https://scontent-lga3-1.xx.fbcdn.net/...",
      "timestamp": "2025-08-24T18:30:00",
      "source": "https://www.facebook.com/marketplace/london/search/?query=iphone",
      "session_id": 18,
      "username": "ebrima"
    }
  ],
  "total_items": 156,
  "page": 1,
  "per_page": 10,
  "total_pages": 16
}

Sessions API

GET /api/sessions

Retrieve user's scraping sessions

Example Request

GET /api/sessions

Example Response

{
  "sessions": [
    {
      "id": 21,
      "name": "London iPhone Scraper",
      "created_at": "2025-08-24T15:16:12",
      "total_items_scraped": 248
    },
    {
      "id": 19,
      "name": "Manchester Electronics",
      "created_at": "2025-08-24T14:20:47",
      "total_items_scraped": 111
    }
  ],
  "user_id": 2,
  "username": "ebrima"
}

POST /sessions/create

Create a new scraping session

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Session name
`urls`	array	Yes	Marketplace URLs to scrape
`interval_type`	string	Yes	seconds, minutes, hours, days
`interval_value`	integer	Yes	Interval numeric value
`max_items`	integer	No	Max items per run (default: 100)

POST /sessions/control/<session_id>

Control session execution (start, pause, stop)

Parameters

Parameter	Type	Description
`action`	string	start, pause, run_once

Notifications API

GET /api/notifications

Retrieve user notifications

Example Response

{
  "notifications": [
    {
      "id": 1,
      "message": "Session 'London Scraper' completed successfully",
      "type": "success",
      "timestamp": "2025-08-24T18:30:00",
      "read": false
    }
  ],
  "unread_count": 3
}

POST /api/notifications/mark-read

Mark notifications as read

Parameters

Parameter	Type	Description
`notification_ids`	array	Array of notification IDs to mark as read

Payments API

POST /payments/create-checkout-session

Create Stripe checkout session

Parameters

Parameter	Type	Description
`price_id`	string	Stripe price ID for subscription tier

Available Price IDs

Basic: price_basic_tier - $9.99/month
Premium: price_premium_tier - $29.99/month
Enterprise: price_enterprise_tier - $99.99/month

POST /payments/webhook

Stripe webhook endpoint (internal use)

This endpoint handles Stripe webhook events for subscription management. It's used internally by Stripe and should not be called directly.

Rate Limits

Rate Limiting: API requests are subject to rate limits based on your subscription tier.

Subscription Tier	Requests per Minute	Requests per Hour	Daily Limit
Free	10	100	1,000
Basic	30	500	5,000
Premium	100	2,000	20,000
Enterprise	Unlimited	Unlimited	Unlimited

Rate Limit Headers

API responses include rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Codes

Status Code	Error Type	Description
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Authentication required
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred

Error Response Format

{
  "error": {
    "code": 400,
    "message": "Invalid session_id parameter",
    "details": "session_id must be a positive integer"
  }
}