Table of Contents

1. API Overview
2. Security & Authentication
3. Core Endpoints
4. Implementation Examples
5. Integration Best Practices
6. Quick Reference Guide
7. Deployment Checklist

1. API Overview

Base Configuration

WordPress REST Base URL:

https://your-site.com/wp-json/

AISEOmatic API Namespaces:

• aiseomatic/v1 – Primary namespace (token-protected)
• aiseoai/v1 – Integration and reporting specific
• aiseomatic-ai/v1 – Open access endpoints

Rate Limiting:

• Default: ~60 requests per 10 minutes per IP address
• Exceeded limit returns HTTP 429 (Too Many Requests)

CORS Support:

• Configurable origin allowlist
• Enable for browser-based applications
• Automatic OPTIONS/preflight handling

2. Security & Authentication

A. API Token Authentication (Recommended)

Configuration: Set your API token in AISEOmatic plugin settings.

Header Requirement:

http

X-Aiseoai-Token: YOUR_TOKEN_HERE
```

**Rate Limiting:**
- Soft limit: 60 requests / 10 minutes / IP address
- Exceeded requests receive HTTP 429 response
- Automatic reset after time window expires

**Security Best Practice:**
Store tokens server-side only. Never expose in client-side code.

---

### B. Signed Links (Select Endpoints)

**Applicable Endpoints:**
- Snapshot exports
- Chunk data exports
- Other sensitive data endpoints

**Access Methods:**

**1. WordPress Admin Session:**
- Logged-in administrator access
- No signature required
- Suitable for internal tools

**2. Public Access Mode:**
- Enable "public snapshots" option in settings
- No authentication required
- Use with caution for sensitive data

**3. Signed URL:**
- Valid signature via `sig` query parameter
- Alternative: `X-AISeoAI-Signature` header
- Generate signatures within WordPress admin
- Share signed URLs with external consumers

**Signature Implementation:**
```
GET /endpoint/{id}?sig=GENERATED_SIGNATURE
```

**Note:** Signature generation handled by plugin. Integration only needs to use provided `sig` value.

---

### C. CORS Configuration

**Purpose:**
Enable browser-based requests from external domains.

**Configuration:**
Add authorized domains to CORS allowlist in plugin settings.

**Example Allowed Origin:**
```
https://app.yourdomain.com

Permitted Headers:

• Content-Type
• X-Aiseoai-Token
• X-AISeoAI-Signature

Response Headers:

http

Access-Control-Allow-Origin: https://app.yourdomain.com
Access-Control-Allow-Headers: Content-Type, X-Aiseoai-Token
Access-Control-Allow-Methods: GET, POST, OPTIONS

Use Cases:

• Webflow frontend integrations
• Ghost CMS themes
• Custom web applications
• JavaScript-based dashboards

3. Core Endpoints

A. aiseomatic/v1 Namespace (Token-Protected)

All endpoints require X-Aiseoai-Token header.

GET /aiseomatic/v1/status

Purpose: Retrieve plugin and site status information

Authentication: Required (Token)

Response Fields:

• Plugin version
• WordPress version
• Site information
• Edition (Pro/Lite)
• License status
• System health indicators

Example Response:

json

{
  "plugin_version": "1.0.0",
  "wordpress_version": "6.4.2",
  "site_url": "https://your-site.com",
  "edition": "Pro",
  "license_status": "active",
  "health": "operational"
}

GET /aiseomatic/v1/sitemap

Purpose: Retrieve AI-optimized sitemap

Authentication: Required (Token)

Response Format: application/xml

Features:

• Basic sitemap (Lite edition)
• Advanced sitemap with AI priorities (Pro edition)
• Real-time content updates
• AI crawler optimization

Response Type:

xml

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://your-site.com/page</loc>
    <lastmod>2025-12-13</lastmod>
    <priority>0.9</priority>
  </url>
</urlset>
```

---

#### GET /aiseomatic/v1/posts

**Purpose:** Retrieve content list with optimization metrics

**Authentication:** Required (Token)

**Query Parameters:**
- `limit` (integer): Maximum results (default: 50)

**Example Request:**
```
GET /aiseomatic/v1/posts?limit=50

Response Fields:

• Content ID
• URL
• AI Score
• has_schema (boolean)
• has_summary (boolean)
• Modified date

Example Response:

json

{
  "posts": [
    {
      "id": 123,
      "url": "https://your-site.com/post-title",
      "score": 85,
      "has_schema": true,
      "has_summary": true,
      "modified": "2025-12-13T10:30:00Z"
    }
  ],
  "total": 150,
  "limit": 50
}

POST /aiseomatic/v1/optimize/{id}

Purpose: Trigger automatic optimization for specific content

Authentication: Required (Token)

Parameters:

• {id} – Content/post ID to optimize

Actions Performed:

• Generate invisible AI summary (Pro)
• Recalculate AI Score
• Update optimization flags
• Refresh structured data

Example Request:

http

POST /aiseomatic/v1/optimize/123
X-Aiseoai-Token: YOUR_TOKEN

Response:

json

{
  "success": true,
  "post_id": 123,
  "new_score": 87,
  "summary_generated": true,
  "optimization_time": "2025-12-13T10:35:00Z"
}

GET /aiseomatic/v1/bots

Purpose: Retrieve recent AI bot visit logs

Authentication: Required (Token)

Query Parameters:

• limit (integer): Maximum results (default: 100)

Response Fields:

• Bot name/identifier
• Visited URL
• Visit timestamp
• User agent
• IP address (if logged)

Example Response:

json

{
  "visits": [
    {
      "bot_name": "GPTBot",
      "url": "/blog/ai-seo-guide",
      "timestamp": "2025-12-13T10:20:00Z",
      "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0"
    },
    {
      "bot_name": "ClaudeBot",
      "url": "/services/local-seo",
      "timestamp": "2025-12-13T09:45:00Z",
      "user_agent": "ClaudeBot/1.0"
    }
  ],
  "total": 1234,
  "limit": 100
}

GET /aiseomatic/v1/schema

Purpose: Retrieve headless-ready JSON-LD structured data

Authentication: Required (Token)

Response Format: Decoded JSON (not encoded in script tags)

Usage: Ready for client-side injection

Example Response:

json

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Your Business Name",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "City",
    "postalCode": "12345"
  },
  "telephone": "+1-555-0100"
}

GET /aiseomatic/v1/image-data/{id}

Purpose: Retrieve AI-optimized image metadata

Authentication: Public by default (configurable)

Parameters:

• {id} – WordPress media/image ID

Response Fields:

• Optimized alt text
• Structured metadata
• AI-generated descriptions
• SEO recommendations

Example Response:

json

{
  "image_id": 456,
  "alt_text": "Modern office workspace with natural lighting",
  "ai_description": "Professional workspace featuring ergonomic desk...",
  "optimization_score": 92,
  "recommendations": ["Add more specific location context"]
}

GET /aiseomatic/v1/ai-data/{id}

Purpose: Retrieve extracted AI data from post/page

Authentication: Public by default (configurable)

Parameters:

• {id} – Post/page ID

Response Fields:

• Extracted entities
• Content chunks
• Semantic analysis
• Topic classification

Example Response:

json

{
  "post_id": 123,
  "entities": ["WordPress", "SEO", "AI optimization"],
  "topics": ["content marketing", "technical SEO"],
  "summary_chunks": ["Introduction to...", "Key benefits..."],
  "semantic_score": 88
}

B. aiseomatic-ai/v1 Namespace (Open Access)

Public endpoints – no authentication required.

GET /aiseomatic-ai/v1/score/{id}

Purpose: Retrieve AI optimization score for content

Authentication: Public

Parameters:

• {id} – Post/page ID

Response:

json

{
  "post_id": 123,
  "score": 85,
  "category": "Very Good",
  "last_updated": "2025-12-13T10:00:00Z"
}

GET /aiseomatic-ai/v1/recommendations/{id}

Purpose: Get optimization improvement suggestions

Authentication: Public

Parameters:

• {id} – Post/page ID

Response:

json

{
  "post_id": 123,
  "current_score": 75,
  "recommendations": [
    {
      "priority": "high",
      "action": "Add AI summary",
      "estimated_impact": "+8 points"
    },
    {
      "priority": "medium",
      "action": "Enhance schema markup",
      "estimated_impact": "+5 points"
    }
  ]
}

C. aiseoai/v1 Namespace (Integration/Reporting)

POST /aiseoai/v1/perf/hit

Purpose: Send lightweight performance/visit signal

Authentication: Public (rate-limited)

Parameters:

• p – Page identifier or URL

Use Case: Analytics tracking, performance monitoring

Rate Limit: Strictly enforced

GET /aiseoai/v1/insights

Purpose: Retrieve comprehensive insights snapshot

Authentication: Admin required

Response: Site-wide analytics and metrics

GET /aiseoai/v1/snapshot/{id}

Purpose: Export complete content snapshot

Authentication: Signature, Admin, or Public mode

Query Parameters:

• sig – Signature for authenticated access

Features:

• ETag support for caching
• HTTP caching headers
• Reduced bandwidth transfers

GET /aiseoai/v1/chunks/{id}

Purpose: Export content chunk data

Authentication: Signature, Admin, or Public mode

Query Parameters:

• sig – Signature for authenticated access

Use Case: Detailed content analysis, migration, backup

Common Error Responses

401 Unauthorized:

json

{
  "code": "rest_forbidden",
  "message": "Missing or invalid authentication token",
  "data": {"status": 401}
}

429 Too Many Requests:

json

{
  "code": "rest_rate_limit",
  "message": "Rate limit exceeded. Try again in 10 minutes.",
  "data": {"status": 429}
}

403 Forbidden:

json

{
  "code": "rest_forbidden",
  "message": "Missing or invalid signature",
  "data": {"status": 403}
}

404 Not Found:

json

{
  "code": "rest_post_invalid_id",
  "message": "Invalid post ID",
  "data": {"status": 404}
}

4. Implementation Examples

cURL (Status Check with Token)

bash

curl -X GET "https://your-site.com/wp-json/aiseomatic/v1/status" \
  -H "X-Aiseoai-Token: YOUR_TOKEN"

JavaScript (Browser – Webflow/Shopify)

Prerequisites:

• Add domain to CORS allowlist in AISEOmatic settings

javascript

fetch('https://your-site.com/wp-json/aiseomatic/v1/posts?limit=20', {
  headers: { 'X-Aiseoai-Token': 'YOUR_TOKEN' },
  credentials: 'omit'
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Next.js (Server-Side API Route – Recommended)

File: app/api/aiseomatic/posts/route.js

javascript

export async function GET() {
  const response = await fetch(
    'https://your-site.com/wp-json/aiseomatic/v1/posts?limit=50',
    {
      headers: { 'X-Aiseoai-Token': process.env.AISEOAI_TOKEN }
    }
  );
  
  const data = await response.text();
  return new Response(data, { 
    status: response.status,
    headers: { 'Content-Type': 'application/json' }
  });
}

Benefits:

• Token kept server-side (secure)
• No client exposure
• CORS not required

Python (requests library)

python

import requests

response = requests.get(
    "https://your-site.com/wp-json/aiseomatic/v1/schema",
    headers={"X-Aiseoai-Token": "YOUR_TOKEN"}
)

print(response.status_code)
print(response.json())

Ruby (Faraday)

ruby

require 'faraday'

conn = Faraday.new('https://your-site.com')
response = conn.get(
  '/wp-json/aiseomatic/v1/bots',
  nil,
  {'X-Aiseoai-Token' => 'YOUR_TOKEN'}
)

puts response.status
puts response.body

Shopify (App Proxy Pattern)

Server-Side (Node.js/Express):

javascript

app.get('/apps/aiseo-proxy', async (req, res) => {
  const apiResponse = await fetch(
    'https://your-site.com/wp-json/aiseomatic/v1/posts',
    {
      headers: { 'X-Aiseoai-Token': process.env.AISEOAI_TOKEN }
    }
  );
  
  const data = await apiResponse.json();
  res.json(data);
});

Benefits:

• Token remains on server
• Avoids storefront CORS issues
• Clean Shopify theme integration

Ghost CMS Integration

Frontend (JavaScript): Use JavaScript example with CORS allowlist configuration.

Server-Side (Helpers/Custom Route): Preferred for security – server-to-server calls with token.

javascript

// Ghost custom helper or route
const fetch = require('node-fetch');

async function getAISeoData() {
  const response = await fetch(
    'https://your-site.com/wp-json/aiseomatic/v1/posts',
    {
      headers: { 'X-Aiseoai-Token': process.env.AISEOAI_TOKEN }
    }
  );
  
  return await response.json();
}

Webflow (Client-Side)

Implementation:

javascript

<script>
  fetch('https://your-site.com/wp-json/aiseomatic/v1/score/123', {
    headers: { 'X-Aiseoai-Token': 'YOUR_TOKEN' }
  })
  .then(r => r.json())
  .then(data => {
    document.getElementById('ai-score').textContent = data.score;
  });
</script>
```

**Configuration Required:**
- Add Webflow domain to CORS allowlist
- Consider security implications of exposed token
- Alternative: Proxy through your server

---

### Signed Link Access (Snapshot/Chunks)

**URL Format:**
```
GET /wp-json/aiseoai/v1/snapshot/{id}?sig=GENERATED_SIGNATURE

Obtaining Signed URL:

1. Generate within WordPress admin
2. Use provided internal tool
3. Or enable public mode (if appropriate)

Features:

• ETag support for efficient caching
• HTTP caching headers reduce bandwidth
• Signature expiration for security

5. Integration Best Practices

Security Guidelines

1. Never Expose Tokens Client-Side

• Always make server-to-server calls when possible
• Use Next.js API routes
• Shopify app servers
• Cloud Functions (AWS Lambda, Google Cloud Functions)
• Backend proxies

2. Client-Side Calls (When Necessary)

• Allowlist domain in CORS settings
• Respect rate limits strictly
• Monitor for token exposure
• Consider using signed links instead

3. Rich Export Security

• Use signed links for snapshots/chunks
• Restrict to admin access when possible
• Enable public mode only if appropriate
• Implement additional application-level security

Error Handling

404 Errors:

• Verify content ID exists
• Check URL construction
• Validate endpoint path

401 Errors:

• Confirm X-Aiseoai-Token header present
• Verify token value correctness
• Check token hasn’t expired

429 Errors:

• Reduce request frequency
• Implement request queuing
• Add exponential backoff
• Cache responses when possible

Performance Optimization

Caching Strategy:

• Implement response caching
• Use ETag headers for snapshots
• Cache static data (schema, config)
• Invalidate on content updates

Request Optimization:

• Batch requests when possible
• Use appropriate limit parameters
• Implement pagination for large datasets
• Compress responses (gzip)

Monitoring:

• Track API usage patterns
• Monitor rate limit proximity
• Log errors for debugging
• Measure response times

6. Quick Reference Guide

7. Deployment Checklist

Pre-Launch Testing

• Test GET /aiseomatic/v1/status (expect HTTP 200)
• Verify token authentication working
• Confirm CORS allowlist configured (if needed)
• Test all required endpoints
• Validate response formats
• Check error handling

Security Configuration

• API token generated and stored securely
• Token stored server-side only (never client)
• CORS allowlist configured if browser calls needed
• Signed exports configured (if using snapshots/chunks)
• Rate limiting understood and planned for

Integration Setup

• Server-side proxy implemented (if exposing to client)
• Error handling implemented
• Caching strategy defined
• Monitoring/logging configured
• Documentation created for team

Optional Configuration

• Public snapshot mode enabled/disabled as needed
• Custom rate limits requested if needed
• Webhook notifications configured
• Backup/export automation set up

Support & Assistance

For API integration support:

Email: contact@aiseomatic.com

Response Time: Under 4 business hours

Documentation: Comprehensive guides available

© 2025 — AISEOmatic — All Rights Reserved

API Version: 1.0 Last Updated: December 13, 2025

This API documentation covers all public and authenticated endpoints. Additional endpoints may be available for specific use cases – contact support for custom integration requirements.

The post AISEOmatic — REST API Integration Guide (Headless & Multi-Platform) appeared first on AISEOmatic.