API Documentation

Integrate AIO Ready's website audit capabilities into your applications with our RESTful API.

API Overview

The AIO Ready API allows you to programmatically audit websites for AI optimization readiness. Our API provides comprehensive analysis across multiple dimensions including content structure, accessibility, performance, and security.

🔑 Authentication

Currently, the API is open and doesn't require authentication. However, we implement rate limiting to ensure fair usage.

⏱️ Rate Limiting

API requests are limited to 10 requests per 15 minutes per IP address. This helps maintain service quality for all users.

Base URL

https://aio.samisen.ai

Response Format

All API responses are returned in JSON format with the following structure:

{
  "success": boolean,
  "audit": {
    "url": "string",
    "domain": "string", 
    "timestamp": "ISO 8601 date",
    "overallScore": number,
    "sections": {
      "contentStructure": { ... },
      "aiAccessibility": { ... },
      "dataQuality": { ... },
      "performance": { ... },
      "structuredData": { ... },
      "socialMedia": { ... },
      "accessibility": { ... },
      "security": { ... }
    }
  },
  "recommendations": [
    {
      "priority": "high|medium|low",
      "title": "string",
      "description": "string", 
      "impact": "string"
    }
  ]
}

API Endpoints

POST Audit Website

Perform a comprehensive AI readiness audit of a website.

Endpoint

POST /api/audit

Request Body

{
  "url": "https://example.com"
}

Parameters

Parameter	Type	Required	Description
url	string	Yes	The URL of the website to audit (must include http:// or https://)

Response Example

200 OK Success Response

{
  "success": true,
  "audit": {
    "url": "https://example.com",
    "domain": "example.com",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "overallScore": 85,
    "sections": {
      "contentStructure": {
        "title": "Content Structure & Markup",
        "score": 90,
        "checks": [
          {
            "name": "Semantic HTML Usage",
            "status": "pass",
            "description": "Found 5 semantic elements: header, nav, main, article, footer"
          }
        ]
      }
    }
  },
  "recommendations": [
    {
      "priority": "medium",
      "title": "Add Descriptive Alt Text to Images",
      "description": "Provide meaningful alt text for all images.",
      "impact": "Medium - Enhances content comprehension for AI"
    }
  ]
}

GET Health Check

Check the status and health of the API service.

Endpoint

GET /api/health

Response Example

200 OK Success Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "1.0.0",
  "uptime": 3600.5,
  "environment": "production"
}

Code Examples

JavaScript/Node.js

const axios = require('axios');

async function auditWebsite(url) {
  try {
    const response = await axios.post('http://localhost:3000/api/audit', {
      url: url
    });
    
    console.log('Audit Score:', response.data.audit.overallScore);
    console.log('Recommendations:', response.data.recommendations);
    
    return response.data;
  } catch (error) {
    console.error('Audit failed:', error.response?.data || error.message);
  }
}

// Example usage
auditWebsite('https://example.com');

Python

import requests
import json

def audit_website(url):
    try:
        response = requests.post('http://localhost:3000/api/audit', 
                               json={'url': url})
        response.raise_for_status()
        
        data = response.json()
        print(f"Audit Score: {data['audit']['overallScore']}")
        print(f"Recommendations: {len(data['recommendations'])} found")
        
        return data
    except requests.exceptions.RequestException as e:
        print(f"Audit failed: {e}")
        return None

# Example usage
audit_website('https://example.com')

cURL

curl -X POST http://localhost:3000/api/audit \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

PHP

$url = 'https://example.com';
$data = json_encode(['url' => $url]);

$ch = curl_init('http://localhost:3000/api/audit');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Audit Score: " . $result['audit']['overallScore'] . "\n";

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Status Code	Description	Example Response
200	Success - Audit completed successfully	Audit results with scores and recommendations
400	Bad Request - Invalid URL or missing parameters	Error message explaining the issue
429	Too Many Requests - Rate limit exceeded	Retry after information
500	Internal Server Error - Server-side issue	Generic error message

Error Response Format

{
  "error": "Error type",
  "message": "Detailed error description",
  "suggestion": "Optional suggestion for resolution"
}

Common Error Examples

Invalid URL

400 Bad Request

{
  "error": "Invalid URL provided",
  "message": "Please provide a valid URL starting with http:// or https://"
}

Rate Limit Exceeded

429 Too Many Requests

{
  "error": "Rate limit exceeded. Please try again later.",
  "retryAfter": 900
}

Website Access Blocked

200 OK (Limited)

{
  "success": true,
  "audit": {
    "overallScore": "N/A",
    "limited": true,
    "sections": { ... }
  },
  "warning": "Limited analysis due to access restrictions",
  "error": "Access denied (403): The website is blocking automated requests"
}