API Integration

API Reference

Atomic Edge provides a RESTful API for programmatic access to your site’s security features. Integrate with WordPress, Laravel, custom applications, and automation workflows.

Overview

Property Value
Base URL https://atomicedge.io/api/v1
Protocol HTTPS only (HTTP requests are rejected)
Format JSON request/response bodies
Authentication API Key via X-AtomicEdge-Key header

Rate Limits

Scope Limit
Read operations (GET) 120 requests/minute per API key
Write operations (POST/PUT/DELETE) 30 requests/minute per API key
Global per IP 300 requests/minute

Rate limit headers are included in all responses:

  • X-RateLimit-Limit — Maximum requests allowed
  • X-RateLimit-Remaining — Requests remaining in current window
  • X-RateLimit-Reset — Unix timestamp when the limit resets

Authentication

All API requests require authentication using an API key.

Generating an API Key

  1. Navigate to your site’s Edit page in the Atomic Edge dashboard
  2. Click the API button in the header actions
  3. Click Generate API Key
  4. Copy the key immediately — it is shown only once

⚠️ Security: Store your API key securely. If compromised or lost, regenerate a new key (this invalidates the previous key).

Request Format

Include the API key in the X-AtomicEdge-Key header:

GET /api/v1/connect HTTP/1.1
Host: atomicedge.io
X-AtomicEdge-Key: YOUR_API_KEY
Content-Type: application/json

cURL example:

curl -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     https://atomicedge.io/api/v1/connect

Response Format

All responses follow a consistent JSON structure:

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable error description."
}

Endpoints

GET /connect

Test API connectivity and retrieve site information.

Authentication: Required

Rate Limit: Read (120/min)

Response

Field Type Description
connected boolean Always true for valid API keys
site_id integer Unique site identifier
domain string Site domain
plan_tier string Plan level: free, advanced, enterprise
waf_enabled boolean WAF protection status
features object Available features for this plan

Example

curl -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     https://atomicedge.io/api/v1/connect
{
  "success": true,
  "data": {
    "connected": true,
    "site_id": 123,
    "domain": "example.com",
    "plan_tier": "advanced",
    "waf_enabled": true,
    "features": {
      "waf_protection": true,
      "analytics": true,
      "ip_access_control": true,
      "geo_blocking": true
    }
  }
}

GET /analytics

Retrieve traffic analytics for your site.

Authentication: Required

Rate Limit: Read (120/min)

Query Parameters

Parameter Type Required Default Description
period string No 24h Time period: 24h, 7d, 30d, 90d

Response

Field Type Description
period string Requested time period
total_requests integer Total requests in period
unique_visitors integer Unique visitor count
requests_blocked integer Requests blocked by WAF
hourly_data array Hourly breakdown of traffic

Example

curl -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     "https://atomicedge.io/api/v1/analytics?period=7d"
{
  "success": true,
  "data": {
    "period": "7d",
    "total_requests": 15420,
    "unique_visitors": 3218,
    "requests_blocked": 127,
    "hourly_data": [
      {
        "hour": "2026-01-05T00:00:00Z",
        "requests": 42,
        "blocked": 2
      }
    ]
  }
}

GET /waf-logs

Retrieve Web Application Firewall log entries.

Authentication: Required

Rate Limit: Read (120/min)

Query Parameters

Parameter Type Required Default Description
page integer No 1 Page number (1-based)
per_page integer No 50 Results per page (10–100)
search string No — Filter by IP, URI, rule ID, or group

Response

Field Type Description
logs array Array of WAF log entries
logs[].id integer Log entry ID
logs[].event_timestamp string ISO 8601 timestamp
logs[].client_ip string Client IP address
logs[].uri string Request URI
logs[].waf_rule_id string Triggered WAF rule ID
logs[].group string WAF rule group
logs[].host string Request host header
pagination object Pagination metadata

Example

curl -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     "https://atomicedge.io/api/v1/waf-logs?page=1&per_page=25"
{
  "success": true,
  "data": {
    "logs": [
      {
        "id": 12345,
        "event_timestamp": "2026-01-05T14:23:45Z",
        "client_ip": "203.0.113.42",
        "uri": "/wp-admin/admin-ajax.php",
        "waf_rule_id": "920350",
        "group": "REQUEST-920-PROTOCOL-ENFORCEMENT",
        "host": "example.com"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 127,
      "total_pages": 6
    }
  }
}

GET /ip-rules

Retrieve current IP whitelist and blacklist rules.

Authentication: Required

Rate Limit: Read (120/min)

Response

Field Type Description
whitelist array Whitelisted IPs/CIDRs
blacklist array Blacklisted IPs/CIDRs
[].ip string IP address or CIDR
[].description string User-provided description
[].added_at string ISO 8601 timestamp

Example

curl -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     https://atomicedge.io/api/v1/ip-rules
{
  "success": true,
  "data": {
    "whitelist": [
      {
        "ip": "192.168.1.0/24",
        "description": "Office network",
        "added_at": "2026-01-01T12:00:00Z"
      }
    ],
    "blacklist": [
      {
        "ip": "203.0.113.42",
        "description": "Malicious actor",
        "added_at": "2026-01-03T08:30:00Z"
      }
    ]
  }
}

POST /ip-rules/whitelist

Add an IP address or CIDR range to the whitelist.

Authentication: Required

Rate Limit: Write (30/min)

Request Body

Parameter Type Required Description
ip string Yes IP address or CIDR (e.g., 192.168.1.1 or 10.0.0.0/8)
description string No Description (max 100 characters)

Response

Returns 201 Created on success.

Example

curl -X POST \
     -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ip": "192.168.1.100", "description": "Developer workstation"}' \
     https://atomicedge.io/api/v1/ip-rules/whitelist
{
  "success": true,
  "message": "IP added to whitelist."
}

POST /ip-rules/blacklist

Add an IP address or CIDR range to the blacklist.

Authentication: Required

Rate Limit: Write (30/min)

Request Body

Parameter Type Required Description
ip string Yes IP address or CIDR (e.g., 203.0.113.42 or 203.0.113.0/24)
description string No Description (max 100 characters)

Example

curl -X POST \
     -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ip": "203.0.113.42", "description": "Malicious actor"}' \
     https://atomicedge.io/api/v1/ip-rules/blacklist

DELETE /ip-rules

Remove an IP address from a whitelist or blacklist.

Authentication: Required

Rate Limit: Write (30/min)

Request Body

Parameter Type Required Description
ip string Yes IP address to remove
type string Yes List type: whitelist or blacklist

Example

curl -X DELETE \
     -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ip": "192.168.1.100", "type": "whitelist"}' \
     https://atomicedge.io/api/v1/ip-rules

GET /geo-rules

Retrieve geographic access control configuration.

Authentication: Required

Rate Limit: Read (120/min)

Response

Field Type Description
enabled boolean Whether geo-blocking is active
mode string whitelist or blacklist
countries array ISO 3166-1 alpha-2 country codes

Example

curl -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     https://atomicedge.io/api/v1/geo-rules
{
  "success": true,
  "data": {
    "enabled": true,
    "mode": "blacklist",
    "countries": ["CN", "RU", "KP"]
  }
}

PUT /geo-rules

Update geographic access control rules.

Authentication: Required

Rate Limit: Write (30/min)

Request Body

Parameter Type Required Description
enabled boolean Yes Enable or disable geo-blocking
mode string Conditional whitelist or blacklist (required if enabled)
countries array Conditional ISO 3166-1 alpha-2 codes (required if enabled)

Example

curl -X PUT \
     -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true, "mode": "blacklist", "countries": ["CN", "RU"]}' \
     https://atomicedge.io/api/v1/geo-rules

WordPress Endpoints

Endpoints prefixed with /wp provide WordPress-specific functionality.

POST /wp/vulnerabilities/check

Check WordPress core, plugins, and themes for known vulnerabilities using the Wordfence Intelligence database.

Authentication: Required

Rate Limit: Write (30/min)

Request Body

Parameter Type Required Description
wordpress_version string Yes WordPress core version (e.g., 6.4.2)
plugins array No Plugins with slug and version
themes array No Themes with slug and version

Response

Field Type Description
checked_at string ISO 8601 timestamp
wordpress.version string Checked WordPress version
wordpress.vulnerabilities array Known vulnerabilities
plugins array Plugin vulnerability results
themes array Theme vulnerability results
summary object Aggregated vulnerability counts
attribution object Data source attribution

Example

curl -X POST \
     -H "X-AtomicEdge-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "wordpress_version": "6.4.2",
       "plugins": [
         {"slug": "contact-form-7", "version": "5.8.4"},
         {"slug": "woocommerce", "version": "8.4.0"}
       ],
       "themes": [
         {"slug": "twentytwentyfour", "version": "1.0"}
       ]
     }' \
     https://atomicedge.io/api/v1/wp/vulnerabilities/check
{
  "success": true,
  "checked_at": "2026-01-06T12:00:00Z",
  "wordpress": {
    "version": "6.4.2",
    "vulnerabilities": []
  },
  "plugins": [
    {
      "slug": "contact-form-7",
      "version": "5.8.4",
      "vulnerabilities": []
    }
  ],
  "themes": [],
  "summary": {
    "total_vulnerabilities": 0,
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "attribution": {
    "provider": "Wordfence Intelligence",
    "provider_url": "https://www.wordfence.com/intelligence/",
    "license": "CC BY-NC-SA 4.0"
  }
}

Error Reference

Response Format

All errors return a consistent JSON structure:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable error description."
}

Error Codes

Code HTTP Status Description
missing_api_key 401 No X-AtomicEdge-Key header provided
invalid_api_key_format 401 API key format is invalid (must be 64 alphanumeric characters)
invalid_api_key 401 API key not found or has been revoked
site_inactive 403 Associated site is not active
site_deleted 403 Associated site has been deleted
feature_unavailable 403 Feature not available on your plan tier
validation_error 422 Request body failed validation
limit_exceeded 403 Plan limit exceeded (e.g., max IPs)
duplicate 409 Resource already exists
no_settings 404 Site settings not configured
rate_limit_exceeded 429 Too many requests

Plan Limits

Resource limits vary by plan tier:

Resource Free Pro Enterprise
Whitelist IPs 5 50 500
Blacklist IPs 5 50 500
Geo Countries 5 50 Unlimited
API Rate (read) 120/min 120/min 120/min
API Rate (write) 30/min 30/min 30/min

Best Practices

Security

  • Never expose API keys in client-side code, version control, or logs
  • Rotate keys periodically and immediately if compromised
  • Use environment variables to store API keys in production

Reliability

  • Implement retry logic with exponential backoff for transient failures
  • Handle rate limits by respecting Retry-After headers on 429 responses
  • Validate responses — always check the success field before processing

Performance

  • Cache read responses when appropriate (analytics, IP rules)
  • Batch operations where possible to reduce API calls
  • Use appropriate timeouts (recommended: 30 seconds)

SDK Examples

PHP (WordPress)

<?php
/**
 * Atomic Edge API Client for WordPress
 */
function atomicedge_api_request($endpoint, $method = 'GET', $data = null) {
    $api_key = get_option('atomicedge_api_key');

    $args = [
        'headers' => [
            'X-AtomicEdge-Key' => $api_key,
            'Content-Type'     => 'application/json',
        ],
        'timeout' => 30,
        'method'  => $method,
    ];

    if ($data !== null && in_array($method, ['POST', 'PUT', 'DELETE'])) {
        $args['body'] = wp_json_encode($data);
    }

    $url = 'https://atomicedge.io/api/v1' . $endpoint;
    $response = wp_remote_request($url, $args);

    if (is_wp_error($response)) {
        return [
            'success' => false,
            'error'   => 'request_failed',
            'message' => $response->get_error_message(),
        ];
    }

    return json_decode(wp_remote_retrieve_body($response), true);
}

// Example: Get analytics
$analytics = atomicedge_api_request('/analytics?period=7d');

// Example: Add IP to blacklist
$result = atomicedge_api_request('/ip-rules/blacklist', 'POST', [
    'ip'          => '203.0.113.42',
    'description' => 'Blocked via API',
]);

JavaScript (Node.js)

const axios = require('axios');

class AtomicEdgeAPI {
  constructor(apiKey) {
    this.client = axios.create({
      baseURL: 'https://atomicedge.io/api/v1',
      headers: {
        'X-AtomicEdge-Key': apiKey,
        'Content-Type': 'application/json',
      },
      timeout: 30000,
    });
  }

  async getAnalytics(period = '24h') {
    const response = await this.client.get('/analytics', {
      params: { period },
    });
    return response.data;
  }

  async addToBlacklist(ip, description = '') {
    const response = await this.client.post('/ip-rules/blacklist', {
      ip,
      description,
    });
    return response.data;
  }

  async getWafLogs(page = 1, perPage = 50) {
    const response = await this.client.get('/waf-logs', {
      params: { page, per_page: perPage },
    });
    return response.data;
  }
}

// Usage
const api = new AtomicEdgeAPI(process.env.ATOMICEDGE_API_KEY);
const analytics = await api.getAnalytics('7d');

Python

import requests
from typing import Optional, List, Dict, Any

class AtomicEdgeAPI:
    """Atomic Edge API Client"""

    BASE_URL = 'https://atomicedge.io/api/v1'

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers.update({
            'X-AtomicEdge-Key': api_key,
            'Content-Type': 'application/json',
        })
        self.session.timeout = 30

    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        response = self.session.request(
            method,
            f'{self.BASE_URL}{endpoint}',
            **kwargs
        )
        response.raise_for_status()
        return response.json()

    def get_analytics(self, period: str = '24h') -> Dict[str, Any]:
        return self._request('GET', '/analytics', params={'period': period})

    def get_waf_logs(self, page: int = 1, per_page: int = 50) -> Dict[str, Any]:
        return self._request('GET', '/waf-logs', params={
            'page': page,
            'per_page': per_page,
        })

    def add_to_blacklist(self, ip: str, description: str = '') -> Dict[str, Any]:
        return self._request('POST', '/ip-rules/blacklist', json={
            'ip': ip,
            'description': description,
        })

# Usage
api = AtomicEdgeAPI('your-api-key-here')
analytics = api.get_analytics('7d')

Support

If you encounter issues with the API:

  1. Verify your API key is correct and not revoked
  2. Check your site is active and on a supported plan
  3. Review error responses for specific error codes and messages
  4. Contact support at support@atomicedge.io if issues persist

Frequently Asked Questions