Table of Contents

🔌 Complete API Reference for External Integrations
📋 Table of Contents
1. API Overview
- Base Configuration
2. Security & Authentication
- A. API Token Authentication (Recommended)
3. Core Endpoints
4. Implementation Examples
5. Integration Best Practices
6. Quick Reference Guide
7. Deployment Checklist
📧 Support & Assistance

🔌 Complete API Reference for External Integrations #

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:

Generate within WordPress admin
Use provided internal tool
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 #

Endpoint	Auth	Description
`GET /aiseomatic/v1/status`	Token	Plugin/site status
`GET /aiseomatic/v1/sitemap`	Token	AI-optimized XML sitemap
`GET /aiseomatic/v1/posts`	Token	Content list with scores
`POST /aiseomatic/v1/optimize/{id}`	Token	Auto-optimize content
`GET /aiseomatic/v1/bots`	Token	AI bot visit logs
`GET /aiseomatic/v1/schema`	Token	Headless JSON-LD
`GET /aiseomatic/v1/image-data/{id}`	Public	Image AI metadata
`GET /aiseomatic/v1/ai-data/{id}`	Public	Post AI extraction
`GET /aiseomatic-ai/v1/score/{id}`	Public	Content AI score
`GET /aiseomatic-ai/v1/recommendations/{id}`	Public	Optimization suggestions
`POST /aiseoai/v1/perf/hit`	Public	Performance signal
`GET /aiseoai/v1/insights`	Admin	Insights snapshot
`GET /aiseoai/v1/snapshot/{id}`	Signature/Admin	Content snapshot export
`GET /aiseoai/v1/chunks/{id}`	Signature/Admin	Content chunks export

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

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.

🔌 Complete API Reference for External Integrations #

📋 Table of Contents #

1. API Overview #

Base Configuration #

2. Security & Authentication #

A. API Token Authentication (Recommended) #

3. Core Endpoints #

A. aiseomatic/v1 Namespace (Token-Protected) #

GET /aiseomatic/v1/status #

GET /aiseomatic/v1/sitemap #

POST /aiseomatic/v1/optimize/{id} #

GET /aiseomatic/v1/bots #

GET /aiseomatic/v1/schema #

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

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

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

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

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

C. aiseoai/v1 Namespace (Integration/Reporting) #

POST /aiseoai/v1/perf/hit #

GET /aiseoai/v1/insights #

GET /aiseoai/v1/snapshot/{id} #

GET /aiseoai/v1/chunks/{id} #

Common Error Responses #

4. Implementation Examples #

cURL (Status Check with Token) #

JavaScript (Browser – Webflow/Shopify) #

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

Python (requests library) #

Ruby (Faraday) #

Shopify (App Proxy Pattern) #

Ghost CMS Integration #

Webflow (Client-Side) #

5. Integration Best Practices #

Security Guidelines #

Error Handling #

Performance Optimization #

6. Quick Reference Guide #

7. Deployment Checklist #

Pre-Launch Testing #

Security Configuration #

Integration Setup #

Optional Configuration #

📧 Support & Assistance #

What are your Feelings

Share This Article :

How can we help?

Leave a Comment Cancel reply

About Us

Help?

Follow Us