Developer API - /llmtag.org

API Overview

The LLMTAG plugin provides a comprehensive REST API for developers to integrate AI protection functionality into custom applications, external systems, and third-party tools.

REST API v1

Full CRUD Operations • Webhook Support • Rate Limiting • Authentication • Comprehensive Documentation

Authentication

API Key Authentication

All API requests require authentication using API keys:

Generate API Key

Go to LLMTAG > Settings > API and click Generate New Key

Configure Permissions

Set the permissions for your API key (read, write, admin)

Set Rate Limits

Configure rate limits for your API key

Test Authentication

Use the API key in your requests to verify authentication

Request Headers

Include the API key in your request headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Rate Limiting

API requests are rate-limited to prevent abuse:

Free Tier

Requests: 1,000 per hour Burst: 100 requests per minute Use for: Development, testing

Pro Tier

Requests: 10,000 per hour Burst: 500 requests per minute Use for: Production applications

Core Endpoints

Settings Management

Get Current Settings

GET /wp-json/llmtag/v1/settings

{
  "protection_mode": "standard",
  "ai_training_data": "disallow",
  "ai_use": ["search_indexing", "generative_synthesis"],
  "blocked_agents": [
    "GPTBot",
    "ChatGPT-User",
    "Claude-Web"
  ],
  "path_protection": {
    "/premium/": {
      "ai_training_data": "disallow",
      "ai_use": ["search_indexing"]
    }
  },
  "analytics_enabled": true,
  "last_updated": "2024-01-15T10:30:00Z"
}

Update Settings

PUT /wp-json/llmtag/v1/settings

{
  "protection_mode": "advanced",
  "ai_training_data": "disallow",
  "ai_use": ["search_indexing", "generative_synthesis", "research"],
  "blocked_agents": [
    "GPTBot",
    "ChatGPT-User",
    "Claude-Web",
    "PerplexityBot"
  ],
  "path_protection": {
    "/premium/": {
      "ai_training_data": "disallow",
      "ai_use": ["search_indexing"]
    },
    "/research/": {
      "ai_training_data": "allow",
      "ai_use": ["search_indexing", "generative_synthesis", "research"]
    }
  }
}

{
  "success": true,
  "message": "Settings updated successfully",
  "data": {
    "protection_mode": "advanced",
    "ai_training_data": "disallow",
    "ai_use": ["search_indexing", "generative_synthesis", "research"],
    "blocked_agents": [
      "GPTBot",
      "ChatGPT-User",
      "Claude-Web",
      "PerplexityBot"
    ],
    "path_protection": {
      "/premium/": {
        "ai_training_data": "disallow",
        "ai_use": ["search_indexing"]
      },
      "/research/": {
        "ai_training_data": "allow",
        "ai_use": ["search_indexing", "generative_synthesis", "research"]
      }
    },
    "last_updated": "2024-01-15T10:35:00Z"
  }
}

Analytics Data

Get Analytics Summary

GET /wp-json/llmtag/v1/analytics/summary

period

string

default:"24h"

Time period for analytics data. Options: 1h, 24h, 7d, 30d

{
  "period": "24h",
  "total_requests": 3642,
  "blocked_requests": 3642,
  "block_success_rate": 100,
  "top_blocked_agents": [
    {
      "agent": "GPTBot",
      "requests": 1247,
      "percentage": 34.2
    },
    {
      "agent": "ChatGPT-User",
      "requests": 892,
      "percentage": 24.5
    }
  ],
  "geographic_distribution": [
    {
      "country": "United States",
      "requests": 2156,
      "percentage": 59.2
    }
  ],
  "hourly_patterns": [
    {
      "hour": "00:00",
      "requests": 12
    }
  ]
}

Get Detailed Analytics

GET /wp-json/llmtag/v1/analytics/detailed

start_date

string

required

Start date for analytics data (ISO 8601 format)

end_date

string

required

End date for analytics data (ISO 8601 format)

agent

string

Filter by specific AI agent

country

string

Filter by geographic location

AI Agent Management

Get Available Agents

GET /wp-json/llmtag/v1/agents

{
  "agents": [
    {
      "id": "gptbot",
      "name": "GPTBot",
      "user_agent": "GPTBot",
      "category": "openai",
      "description": "OpenAI's web crawler for training GPT models",
      "default_action": "block",
      "threat_level": "high"
    },
    {
      "id": "chatgpt-user",
      "name": "ChatGPT-User",
      "user_agent": "ChatGPT-User",
      "category": "openai",
      "description": "ChatGPT browsing feature",
      "default_action": "block",
      "threat_level": "medium"
    }
  ],
  "categories": [
    {
      "id": "openai",
      "name": "OpenAI Agents",
      "count": 3
    },
    {
      "id": "google",
      "name": "Google AI",
      "count": 4
    }
  ]
}

Update Agent Status

PUT /wp-json/llmtag/v1/agents/{agent_id}

{
  "action": "allow",
  "reason": "Research purposes",
  "expires_at": "2024-02-15T00:00:00Z"
}

llmtag.txt Management

Get Current llmtag.txt

GET /wp-json/llmtag/v1/llmtag-txt

spec_version: 3.0
ai_training_data: disallow
ai_use: search_indexing, generative_synthesis

# Protect premium content
Path: /premium/
ai_training_data: disallow
ai_use: search_indexing

# Allow research bots
User-agent: ResearchBot
ai_training_data: allow
ai_use: research

Regenerate llmtag.txt

POST /wp-json/llmtag/v1/llmtag-txt/regenerate

{
  "success": true,
  "message": "llmtag.txt regenerated successfully",
  "url": "https://example.com/llmtag.txt",
  "last_updated": "2024-01-15T10:40:00Z"
}

Webhook Integration

Webhook Configuration

Set up webhooks to receive real-time notifications:

Create Webhook

Go to LLMTAG > Settings > Webhooks and click Add Webhook

Configure Endpoint

Set the URL where webhook events should be sent

Select Events

Choose which events to receive notifications for

Set Authentication

Configure authentication for your webhook endpoint

Test Webhook

Send a test event to verify the webhook is working

Available Webhook Events

Agent Blocked

Triggered when an AI agent is blocked:

{
  "event": "agent.blocked",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "agent": "GPTBot",
    "user_agent": "GPTBot",
    "ip_address": "192.168.1.100",
    "path": "/blog/post-1",
    "reason": "Blocked by policy",
    "request_id": "req_123456789"
  }
}

Settings Updated

Triggered when plugin settings are updated:

{
  "event": "settings.updated",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "updated_by": "admin",
    "changes": [
      {
        "field": "ai_training_data",
        "old_value": "allow",
        "new_value": "disallow"
      }
    ]
  }
}

New Agent Detected

Triggered when a new AI agent is detected:

{
  "event": "agent.detected",
  "timestamp": "2024-01-15T10:40:00Z",
  "data": {
    "agent": "NewAI-Bot",
    "user_agent": "NewAI-Bot/1.0",
    "ip_address": "192.168.1.101",
    "path": "/",
    "first_seen": "2024-01-15T10:40:00Z"
  }
}

Webhook Security

Signature Verification

All webhooks include a signature for verification:

// Example webhook signature verification
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

SDK and Libraries

JavaScript SDK

// Install: npm install llmtag-wp-sdk
import { LLMTAGClient } from 'llmtag-wp-sdk';

const client = new LLMTAGClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-site.com'
});

// Get current settings
const settings = await client.settings.get();

// Update settings
await client.settings.update({
  protection_mode: 'advanced',
  ai_training_data: 'disallow'
});

// Get analytics
const analytics = await client.analytics.getSummary('24h');

PHP SDK

// Install: composer require llmtag/wordpress-sdk
use LLMTAG\WordPress\Client;

$client = new Client([
    'api_key' => 'your-api-key',
    'base_url' => 'https://your-site.com'
]);

// Get current settings
$settings = $client->settings()->get();

// Update settings
$client->settings()->update([
    'protection_mode' => 'advanced',
    'ai_training_data' => 'disallow'
]);

// Get analytics
$analytics = $client->analytics()->getSummary('24h');

Python SDK

# Install: pip install llmtag-wp-sdk
from llmtag_wp_sdk import LLMTAGClient

client = LLMTAGClient(
    api_key='your-api-key',
    base_url='https://your-site.com'
)

# Get current settings
settings = client.settings.get()

# Update settings
client.settings.update({
    'protection_mode': 'advanced',
    'ai_training_data': 'disallow'
})

# Get analytics
analytics = client.analytics.get_summary('24h')

Error Handling

Error Response Format

All API errors follow a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid",
    "details": {
      "field": "ai_training_data",
      "reason": "Invalid value. Must be 'allow' or 'disallow'"
    }
  }
}

Common Error Codes

Authentication Errors

INVALID_API_KEY
API_KEY_EXPIRED
INSUFFICIENT_PERMISSIONS

Validation Errors

INVALID_REQUEST
MISSING_REQUIRED_FIELD
INVALID_VALUE

Rate Limiting

RATE_LIMIT_EXCEEDED
QUOTA_EXCEEDED

Server Errors

INTERNAL_ERROR
SERVICE_UNAVAILABLE
DATABASE_ERROR

Error Handling Best Practices

Check HTTP Status Codes

Always check the HTTP status code before processing the response

Handle Rate Limiting

Implement exponential backoff for rate limit errors

Validate Responses

Validate API responses before using the data

Log Errors

Log API errors for debugging and monitoring

Testing and Development

API Testing

Using cURL

# Test authentication
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://your-site.com/wp-json/llmtag/v1/settings

# Update settings
curl -X PUT \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"protection_mode": "advanced"}' \
     https://your-site.com/wp-json/llmtag/v1/settings

Using Postman

Import the API collection from the plugin documentation
Set your API key in the collection variables
Test each endpoint to verify functionality

Development Environment

Set Up Local Environment

Install WordPress locally with the LLMTAG plugin

Enable Debug Mode

Enable WordPress debug mode for detailed error messages

Generate Test API Key

Create a test API key with full permissions

Test All Endpoints

Verify all API endpoints work correctly

Best Practices

API Usage

Use Appropriate HTTP Methods

Use GET for reading data, PUT for updates, POST for actions

Implement Caching

Cache API responses to reduce server load and improve performance

Handle Errors Gracefully

Implement proper error handling and user feedback

Respect Rate Limits

Implement rate limiting in your applications to avoid hitting API limits

Security

Always follow security best practices when using the API:

Secure API Keys: Store API keys securely and never expose them in client-side code
Use HTTPS: Always use HTTPS for API requests
Validate Input: Validate all input data before sending API requests
Monitor Usage: Monitor API usage for unusual patterns or abuse
Regular Rotation: Regularly rotate API keys for security

Performance

Follow these tips to optimize API performance:

Batch Requests: Combine multiple operations into single requests when possible
Use Pagination: Use pagination for large data sets
Implement Caching: Cache frequently accessed data
Monitor Response Times: Track API response times and optimize as needed
Use Webhooks: Use webhooks instead of polling for real-time updates

Installation

Features

Advanced

​API Overview

REST API v1

​Authentication

​API Key Authentication

​Request Headers

​Rate Limiting

Free Tier

Pro Tier

​Core Endpoints

​Settings Management

​Get Current Settings

​Update Settings

​Analytics Data

​Get Analytics Summary

​Get Detailed Analytics

​AI Agent Management

​Get Available Agents

​Update Agent Status

​llmtag.txt Management

​Get Current llmtag.txt

​Regenerate llmtag.txt

​Webhook Integration

​Webhook Configuration

​Available Webhook Events

​Agent Blocked

​Settings Updated

​New Agent Detected

​Webhook Security

​Signature Verification

​SDK and Libraries

​JavaScript SDK

​PHP SDK

​Python SDK

​Error Handling

​Error Response Format

​Common Error Codes

Authentication Errors

Validation Errors

Rate Limiting

Server Errors

​Error Handling Best Practices

​Testing and Development

​API Testing

​Using cURL

​Using Postman

​Development Environment

​Best Practices

​API Usage

Use Appropriate HTTP Methods

Implement Caching

Handle Errors Gracefully

Respect Rate Limits

​Security

​Performance

API Overview

Authentication

API Key Authentication

Request Headers

Rate Limiting

Core Endpoints

Settings Management

Get Current Settings

Update Settings

Analytics Data

Get Analytics Summary

Get Detailed Analytics

AI Agent Management

Get Available Agents

Update Agent Status

llmtag.txt Management

Get Current llmtag.txt

Regenerate llmtag.txt

Webhook Integration

Webhook Configuration

Available Webhook Events

Agent Blocked

Settings Updated

New Agent Detected

Webhook Security

Signature Verification

SDK and Libraries

JavaScript SDK

PHP SDK

Python SDK

Error Handling

Error Response Format

Common Error Codes

Error Handling Best Practices

Testing and Development

API Testing

Using cURL

Using Postman

Development Environment

Best Practices

API Usage

Security

Performance