API Reference

Complete reference for all FreeAI API endpoints. All requests use JSON format and return standardized responses.

Base URL

https://your-domain.vercel.app/api

Authentication

FreeAI APIs are currently open and do not require authentication. For production deployments, consider implementing your own authentication layer.

Note: Future versions will include API key authentication for enhanced security.

Chat API

The Chat API provides AI-powered conversational capabilities with support for multiple providers.

POST /api/chat

Send a message to the AI and receive a response.

Request

{
  "message": "string (required)",
  "options": {
    "provider": "gemini | chatgpt | groq | auto",
    "temperature": 0.7,
    "maxTokens": 1000,
    "stream": false
  }
}

Parameters

message(required)

The message to send to the AI.

provider(optional)

AI provider to use. Defaults to "auto" for intelligent selection.

temperature(optional)

Controls randomness. Range: 0.0 to 1.0. Default: 0.7

Response

{
  "response": "AI response content",
  "provider": "gemini",
  "timestamp": "2024-12-06T10:30:00.000Z",
  "usage": {
    "tokens": 150,
    "cost": 0.001
  }
}

Example

curl -X POST https://your-domain.vercel.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain web automation",
    "options": {
      "provider": "gemini",
      "temperature": 0.7
    }
  }'

Automation API

The Automation API provides browser automation capabilities for web scraping and interaction.

POST /api/automation

Execute browser automation tasks.

Request

{
  "url": "string (required)",
  "actions": [
    {
      "type": "click | type | wait | screenshot",
      "selector": "string",
      "value": "string",
      "timeout": 5000
    }
  ],
  "options": {
    "stealth": true,
    "headless": true,
    "viewport": {
      "width": 1920,
      "height": 1080
    }
  }
}

Response

{
  "success": true,
  "results": [
    {
      "action": "screenshot",
      "data": "base64_image_data",
      "timestamp": "2024-12-06T10:30:00.000Z"
    }
  ],
  "metadata": {
    "executionTime": 2340,
    "userAgent": "Mozilla/5.0..."
  }
}

Extract API

The Extract API combines AI and web automation to extract structured data from websites.

POST /api/extract

Extract structured data from web pages using AI.

Request

{
  "url": "string (required)",
  "schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "price": { "type": "number" },
      "availability": { "type": "boolean" }
    },
    "required": ["title", "price"]
  },
  "options": {
    "provider": "gemini",
    "stealth": true,
    "waitFor": "networkidle0"
  }
}

Response

{
  "success": true,
  "data": {
    "title": "Wireless Headphones",
    "price": 99.99,
    "availability": true
  },
  "confidence": 0.95,
  "provider": "gemini",
  "extractionTime": 1240
}

Error Responses

All APIs return standardized error responses in the following format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: message",
    "details": {
      "parameter": "message",
      "expected": "string"
    }
  },
  "timestamp": "2024-12-06T10:30:00.000Z"
}

Common Error Codes

INVALID_REQUEST - Request validation failed

PROVIDER_ERROR - AI provider returned an error

AUTOMATION_FAILED - Browser automation failed

RATE_LIMITED - Too many requests

INTERNAL_ERROR - Server error

Rate Limits

Chat API

100 requests/minute

Automation API

20 requests/minute

Extract API

30 requests/minute

SDKs & Code Examples

JavaScript/Node.js

// Using fetch API
async function chatWithAI(message) {
  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message })
  });
  
  const data = await response.json();
  return data.response;
}

// Example usage
const answer = await chatWithAI('What is web automation?');
console.log(answer);

Python

import requests

def chat_with_ai(message):
    response = requests.post('https://your-domain.vercel.app/api/chat', 
                           json={'message': message})
    return response.json()['response']

# Example usage
answer = chat_with_ai('Explain Puppeteer')
print(answer)

curl

# Basic chat request
curl -X POST https://your-domain.vercel.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, FreeAI!"}'

# Data extraction request  
curl -X POST https://your-domain.vercel.app/api/extract \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product",
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "price": {"type": "number"}
      }
    }
  }'

Need Help?

Having trouble with the API? Check our support documentation orcontact us for assistance.