Authentication

All API requests require authentication using an API key. API keys provide secure access to the Pondral AEO platform and can be scoped to specific permissions.

Getting Your API Key

Log in to your Pondral AEO dashboard
Navigate to Settings → API Keys
Click "Create New Key"
Give your key a descriptive name (e.g., "Production API Key")
Select the scopes your application needs
Copy and save the key securely (it won't be shown again)

Making Authenticated Requests

Include your API key in the Authorization header with the Bearer scheme:

curl -X GET https://app.pondral.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript / TypeScript

const response = await fetch(
  'https://app.pondral.com/api/v1/projects',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);
const data = await response.json();

API Key Scopes

Scopes limit what an API key can do. Create keys with only the scopes you need for better security.

Scope	Description
`analyze`	Run AI visibility analyses
`projects`	Create and list projects
`results`	Read analysis results
`reports`	Access generated reports
`monitoring`	Manage monitoring schedules
`webhooks`	Create and manage webhooks
`usage`	View usage statistics

Security Best Practices

Never commit API keys to version control
Use environment variables to store API keys securely
Use separate API keys for different environments (dev, staging, prod)
Rotate API keys regularly
Revoke keys immediately if they are compromised
Only request the minimum scopes needed for your use case
Verify webhook signatures using the provided secret

Rate Limits

API requests are rate-limited based on your subscription tier. Limits are reset every 60 seconds. The remaining requests in the current window are returned in the X-RateLimit-Remaining header.

Free

10 req/min

SMB

60 req/min

Growth

300 req/min

Scale

1,000 req/min

Error Codes & Status Codes

Code	HTTP Status	Meaning
`INVALID_API_KEY`	401	API key is missing, invalid, or expired
`INSUFFICIENT_SCOPE`	403	API key does not have permission for this endpoint
`RATE_LIMIT_EXCEEDED`	429	Too many requests in the time window
`VALIDATION_ERROR`	400	Invalid request parameters or body
`NOT_FOUND`	404	The requested resource does not exist
`BILLING_LIMIT_EXCEEDED`	403	Monthly usage limit reached for this tier
`ENGINE_FAILURE`	502	AI engine error (try again or use different engine)
`INTERNAL_ERROR`	500	Server error (try again or contact support)

Webhook Security

All webhook payloads are signed with an HMAC-SHA256 signature using your webhook secret. Verify the signature to ensure the webhook came from Pondral.

Verifying Signatures (Node.js)

import crypto from 'crypto';

export function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(hmac),
    Buffer.from(signature)
  );
}

// In your webhook handler:
const signature = req.headers['x-pondral-signature'];
const payload = req.body.toString();

if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

// Process webhook...

The signature is provided in the X-Pondral-Signature header. Always verify this before processing webhook events.