Traffic Torch – Developer API

Q: How do I get an API key?

Generate one on this page after logging in. Use the 'Generate New Key' button.

Q: Can I revoke an API key?

Yes – click 'Revoke' next to any key on this page. Revoked keys are immediately invalid.

Q: What events trigger webhooks?

Currently only audit.completed. usage.alert (when you reach 80% of your daily limit) is planned.

🔑 Your API Keys

Loading keys…

Your new API key:

Copy this key now. It will not be shown again.

📡 Webhooks

Receive real‑time notifications when audits complete.

No webhooks configured.

📖 API Endpoints (Quick Reference)

All endpoints require authentication via X-API-Key or Authorization header (see Authentication).

POST /api/tools/:tool Run audit

Run any audit tool. Replace :tool with: seo-intent, seo-ux, local-seo, product-seo, entity, topical, schema-generator, ai-search, ai-voice, ai-audit, quit-risk, keyword-research, keyword-placement.

POST /api/tools/seo-intent
X-API-Key: YOUR_API_KEY
{"url": "https://example.com"}

GET / POST / DELETE /api/webhooks Webhooks

Manage your webhooks. POST with { url, events: ["audit.completed"] }, GET to list, DELETE /:id to remove.

GET /api/account-info Account

Get your account details, including remaining daily usage.

GET / POST / DELETE /api/keys API Keys

List, generate, and revoke API keys (managed above).

📊 Rate Limits (Summary)

Free: 3 req/day

Pro: 25 req/day

Enterprise: 300 req/day

Remaining today:

See detailed rate limit documentation for more info.

🔐 Authentication

↑ Back to Top

All API requests require authentication. There are two types of credentials:

Bearer Token (JWT) – used for most endpoints (keys, webhooks, account info). Obtain it by logging in via the login page.
X-API-Key – used exclusively for the tool endpoint /api/tools/*. Generate a key on this page.

Authorization: Bearer <your_jwt>
X-API-Key: <your_api_key>

The X-API-Key header is only required for the tool endpoint; all other endpoints use the Authorization header.

📡 Endpoints Overview

↑ Back to Top

Method	Endpoint	Description
GET	/api/keys	List your API keys
POST	/api/keys/generate	Generate a new API key
DELETE	/api/keys/revoke/:id	Revoke an API key
POST	/api/tools/:tool	Run an audit (requires X-API-Key)
GET	/api/webhooks	List your webhooks
POST	/api/webhooks	Create a webhook
DELETE	/api/webhooks/:id	Delete a webhook
GET	/api/account-info	Get account details & usage

🛠️ Tool Endpoint

↑ Back to Top

POST /api/tools/:tool

Headers: X-API-Key: <your_api_key> and Content-Type: application/json

Request body:

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

Response (success):

{
  "success": true,
  "data": {
    "tool": "seo-intent",
    "url": "https://example.com",
    "score": 85,
    "summary": "Good intent match"
  }
}

Available tools: seo-intent, seo-ux, local-seo, product-seo, entity, topical, schema-generator, ai-search, ai-voice, ai-audit, quit-risk, keyword-research, keyword-placement.

🔗 Webhook Endpoints (Detailed)

↑ Back to Top

GET /api/webhooks – list your webhooks (requires Bearer token).

POST /api/webhooks – create a new webhook (requires Bearer token).

{
  "url": "https://your-domain.com/webhook",
  "events": ["audit.completed"]
}

DELETE /api/webhooks/:id – delete a webhook (requires Bearer token).

All webhook endpoints return JSON with { success: true, ... } or an error object.

👤 Account Info

↑ Back to Top

GET /api/account-info – returns your account details and daily usage.

Response example:

{
  "email": "[email protected]",
  "isPro": true,
  "proSince": "2025-03-01T...",
  "dailyUsed": 3,
  "dailyLimit": 25,
  "dailyRemaining": 22,
  "tier": "pro",
  "ga4Connected": true,
  "gscConnected": true,
  "gscSiteUrl": "sc-domain:example.com"
}

❌ Error Codes

↑ Back to Top

Status	Meaning	Common Cause
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Missing/invalid Bearer token or X-API-Key
403	Forbidden	You don't own the resource (e.g., revoking someone else's key)
404	Not Found	Endpoint or resource ID does not exist
429	Too Many Requests	Daily rate limit exceeded
500	Internal Server Error	Unexpected server issue – contact support

All error responses include an error field with a description.

📊 Rate Limits (Detailed)

↑ Back to Top

Daily request limits are applied per API key (for the tool endpoint) and per user (for other endpoints). The limit depends on your subscription tier:

Free: 3 req/day

Pro: 25 req/day

Enterprise: 300 req/day

The /api/account-info endpoint returns your current usage and remaining requests.

Note: The tool endpoint (/api/tools/*) counts against the API key's daily limit. Other endpoints (keys, webhooks, account) are not rate-limited (but may be in the future).

💻 Code Examples

↑ Back to Top

cURL

curl -X POST https://traffic-torch-auth.traffictorch.workers.dev/api/tools/seo-intent \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

JavaScript (fetch)

fetch('https://traffic-torch-auth.traffictorch.workers.dev/api/tools/seo-intent', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com' })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

Python (requests)

import requests

url = 'https://traffic-torch-auth.traffictorch.workers.dev/api/tools/seo-intent'
headers = {'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json'}
payload = {'url': 'https://example.com'}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

PHP (cURL)

$ch = curl_init('https://traffic-torch-auth.traffictorch.workers.dev/api/tools/seo-intent');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: YOUR_API_KEY',
  'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['url' => 'https://example.com']));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

📦 Webhook Payload

↑ Back to Top

When an audit completes, Traffic Torch sends a POST request to your registered webhook URL with the following JSON payload:

{
  "event": "audit.completed",
  "tool": "seo-intent",
  "url": "https://example.com",
  "result": {
    "tool": "seo-intent",
    "url": "https://example.com",
    "score": 85,
    "summary": "Good intent match"
  },
  "timestamp": "2025-03-01T12:34:56.789Z"
}

The result field contains the exact response you'd get from the tool endpoint.

Event types: audit.completed (currently the only event). usage.alert will be added in the future.

❓ FAQ

↑ Back to Top

How do I get an API key?

Generate one on this page after logging in. Use the "Generate New Key" button.

What's the difference between the Bearer token and X-API-Key?

The Bearer token (JWT) is used for management endpoints (keys, webhooks). The X-API-Key is used exclusively for running audits via /api/tools/*.

How are daily limits calculated?

The limit applies to the API key (for tool calls) and resets at midnight UTC. The /api/account-info endpoint shows your current usage and remaining requests.

Can I revoke an API key?

Yes – click "Revoke" next to any key on this page. Revoked keys are immediately invalid.

What events trigger webhooks?

Currently only audit.completed. usage.alert (when you reach 80% of your daily limit) is planned.

Is there a test environment?

The same endpoints work for both live and test; you can use https://webhook.site to test webhooks.

Do you have a sandbox mode?

Not yet, but you can create a test API key and use it with your own development environment.

📅 Changelog

↑ Back to Top

v1.0.0 – March 1, 2025

Initial API release
Support for 13 audit tools
API key generation and revocation
Webhook management (audit.completed)
Account info and rate limits

Future versions will include additional tools, event types, and pagination.

📧 Support

↑ Back to Top

For API support, bug reports, or feature requests, please contact us:

Email: [email protected]
Help Guides: traffictorch.net/ai-ux-seo-help-guides

We aim to respond within 24 hours (business days).

🧑‍💻 Developer API

🔑 Your API Keys

📡 Webhooks

📖 API Endpoints (Quick Reference)

📊 Rate Limits (Summary)

🔐 Authentication

📡 Endpoints Overview

🛠️ Tool Endpoint

🔗 Webhook Endpoints (Detailed)

👤 Account Info

❌ Error Codes

📊 Rate Limits (Detailed)

💻 Code Examples

cURL

JavaScript (fetch)

Python (requests)

PHP (cURL)

📦 Webhook Payload

❓ FAQ

📅 Changelog

📧 Support