API Reference

Complete documentation for the Pondral REST API v1 — Enterprise Edition

POST/api/v1/analyze

Run Analysis

Execute a single analysis on a question to determine brand citation rates across AI engines.

Parameters

Name	Type	Required	Description
project_id	string	Yes	The project ID to analyze within
question	string	Yes	The search question (max 500 chars)
engine	string	No	AI engine: claude, chatgpt, perplexity, or gemini
brand	string	No	Brand name (uses project default if omitted)
website	string	No	Brand website URL
industry	string	No	Industry classification
competitor	string	No	Competitor name
comp_website	string	No	Competitor website URL

Request Body

{
  "project_id": "proj_abc123",
  "question": "What are the best tools for content optimization?",
  "engine": "claude",
  "brand": "Pondral",
  "website": "https://pondral.com"
}

Response

{
  "data": {
    "id": "result_xyz789",
    "run_id": "run_def456",
    "result": {
      "ai_answer": "Several tools are excellent for content optimization...",
      "sources_found": [
        "example.com",
        "blog.example.com"
      ],
      "brand_analysis": {
        "cited": true,
        "mentioned": true,
        "citation_context": "Pondral is known for...",
        "citation_strength": 85,
        "content_found": "Brand page about optimization strategies",
        "recommendation": "Increase content depth around AI citations"
      },
      "competitor_analysis": {
        "cited": true,
        "mentioned": true,
        "citation_context": "Similar solutions include...",
        "citation_strength": 72
      },
      "engine": "claude"
    }
  }
}

Code Examples

curl -X POST https://api.pondral.com/api/v1/analyze \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "question": "What are the best tools for content optimization?",
    "engine": "claude"
  }'

Authentication

All requests require authentication via Bearer token in the Authorization header:

Authorization: Bearer sk_live_abc123def456

API keys are created in your account settings. Keep your API keys secure and regenerate them if compromised. Keys are hashed and never stored in plaintext.

Rate Limits by Tier

Tier	Requests/Min	Monthly Analyses	Monitoring	Reports
Free	10	100	—	—
Starter	60	1000	—	—
Growth	300	10000	✓	—
Agency	1000	50000	✓	✓
Enterprise	5000	Unlimited	✓	✓

Rate limit status is returned in response headers as X-RateLimit-Remaining. When limit is reached (status 429), retry after the seconds specified in the Retry-After header.

Error Codes

Code	Status	Description
INVALID_API_KEY	401	API key is missing or invalid
INSUFFICIENT_SCOPE	403	API key does not have required permissions
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded. Retry after specified seconds.
VALIDATION_ERROR	400	Invalid request parameters
NOT_FOUND	404	Resource not found
FORBIDDEN	403	Access denied to resource
BILLING_LIMIT_EXCEEDED	403	Monthly analysis quota reached
ENGINE_FAILURE	502	AI engine temporarily unavailable
DATABASE_ERROR	500	Database operation failed
INTERNAL_ERROR	500	Internal server error

Best Practices

Security

Rotate API keys regularly
Never commit keys to version control
Use environment variables for secrets
Regenerate compromised keys immediately

Performance

Implement exponential backoff for retries
Cache results when appropriate
Use pagination for large datasets
Monitor rate limit headers

Ready to Get Started?

Generate an API key in your account settings and start making requests. Enterprise tier provides 5000 requests/minute and unlimited monthly analyses.