SEO Agents API Reference

The AI SEO Agents API is a REST API hosted at https://api.aiagentssee.com/v1/. All endpoints require authentication via Cognito JWT or API key, following industry standards outlined in the OAuth 2.0 Authorization Framework (RFC 6749). Responses are JSON-encoded. The API design follows principles from the Google API Design Guide, including resource-oriented URLs and standard HTTP methods. For a complete platform overview before diving into the API, see the Quick Start Guide. The API currently processes thousands of requests daily across hundreds of managed sites, with 99.9% uptime over the past 12 months.

Authentication

The API supports two authentication methods. Include one of the following headers with every request:

Choosing an Authentication Method

The right authentication method depends on your integration type and security requirements. Based on patterns from over 500 API integrations across our customer base, here is how the two methods compare:

For most production integrations, we recommend starting with API keys for simplicity, then migrating to JWT if you need per-user access control or MFA enforcement. Agencies managing client sites typically use one API key per client site for clean separation of rate limits and audit trails.

Base URL

https://api.aiagentssee.com/v1/dashboard

SEO Agents API Endpoints

Agents

Jobs

Articles

Sites

Other

Creating a Job — Example

curl -X POST https://api.aiagentssee.com/v1/dashboard/jobs \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-a1b2c3d4",
    "job_type": "create",
    "keyword": "best trade show booths 2026"
  }'

Response:

{
  "job_id": "content-a1b2c3d4",
  "status": "pending",
  "keyword": "best trade show booths 2026",
  "agent_id": "agent-a1b2c3d4",
  "created_at": "2026-02-26T10:30:00Z"
}

Rate Limits

Rate Limit Best Practices

Production integrations that process hundreds of articles per month need a robust rate limiting strategy. Based on our experience supporting high-volume agency deployments, these patterns prevent disruptions:

• Exponential backoff with jitter — When you receive a 429 response, wait for the Retry-After header value, then add random jitter (0-500ms) to prevent thundering herd problems when multiple clients retry simultaneously.
• Request queuing — For batch operations (e.g., publishing 20 articles), queue requests and process them at 80% of your plan's rate limit. This leaves headroom for interactive dashboard requests.
• Circuit breaker pattern — After 3 consecutive 429 responses, pause all requests for 30 seconds before resuming. This prevents wasting API calls during rate limit windows.

import time
import random

def api_request_with_backoff(url, headers, max_retries=5):
    """Exponential backoff with jitter for rate-limited APIs."""
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
        jitter = random.uniform(0, 0.5)
        time.sleep(retry_after + jitter)
    raise Exception("Max retries exceeded")

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include a JSON body with a message field describing the problem and, where applicable, a code field with a machine-readable error identifier. Your client application should handle these error categories gracefully to provide a reliable integration.

// Example error response
{
  "message": "Agent not found: agent-xyz12345",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req-a1b2c3d4-5678-90ab-cdef"
}

Common Error Scenarios

These are the most frequently encountered error patterns based on analysis of support tickets from our customer base. Each scenario includes the root cause and recommended fix:

Pagination

List endpoints that return multiple items support cursor-based pagination. This is more efficient than offset-based pagination for large datasets because it avoids the performance degradation that occurs when skipping many records. Pagination parameters are passed as query string parameters and pagination metadata is returned in the response body.

# First page
curl "https://api.aiagentssee.com/v1/dashboard/articles?limit=10" \
  -H "Authorization: Bearer <id_token>"

# Next page (using cursor from previous response)
curl "https://api.aiagentssee.com/v1/dashboard/articles?limit=10&cursor=eyJzayI6IjIwMjYtMDItMjUifQ" \
  -H "Authorization: Bearer <id_token>"

The response includes a next_cursor field when more results are available. When next_cursor is null, you have reached the end of the result set. Cursors are opaque strings that encode the position in the dataset — do not attempt to decode or construct them manually.

Webhook Callbacks

Instead of polling the API for job status updates, you can configure webhook callbacks to receive push notifications when events occur. Webhooks are the recommended approach for production integrations because they reduce API calls, provide lower latency, and eliminate the complexity of managing polling loops. See the dedicated Webhook Setup guide for complete configuration instructions.

• Job completion: Triggered when a content, publish, or audit job reaches a terminal state (completed or failed). The payload includes the job ID, final status, result summary, and the S3 key for generated artifacts.
• Article published: Triggered when an article is successfully published to WordPress. The payload includes the WordPress post ID, URL, publish status, and the SEO score at time of publication.
• Rank alert: Triggered when a keyword ranking change exceeds your configured threshold. The payload includes the keyword, old position, new position, and the page URL that ranks.
• Audit complete: Triggered when a site-wide audit finishes. The payload includes the overall site score, number of issues found by severity, and a presigned URL for the full report.

SEO Agents API Code Examples

The following examples demonstrate the most common API operations. All examples use curl for clarity, but the API works with any HTTP client. Replace <id_token> with your Cognito JWT or use -H "X-API-Key: sak_your_key" for API key authentication.

Create an Agent

curl -X POST https://api.aiagentssee.com/v1/dashboard/agents \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trade Show Content Agent",
    "keywords": ["trade show booth cost", "custom trade show booth"],
    "tone": "professional",
    "word_target": 2500,
    "schedule": "weekly"
  }'

List Articles with Filtering

# List articles for a specific agent, sorted by SEO score
curl "https://api.aiagentssee.com/v1/dashboard/articles?agent_id=agent-a1b2c3d4&sort=score:desc&limit=20" \
  -H "X-API-Key: sak_your_api_key"

Poll Job Progress

# Get progress events since a specific timestamp
curl "https://api.aiagentssee.com/v1/dashboard/jobs/content-a1b2c3d4/progress?since=2026-02-26T10:30:00Z" \
  -H "Authorization: Bearer <id_token>"

Trigger a Publish Job

curl -X POST https://api.aiagentssee.com/v1/dashboard/jobs \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-a1b2c3d4",
    "job_type": "publish",
    "s3_key": "articles/agent-a1b2c3d4/trade-show-booth-cost.md",
    "publish_action": "elementor_publish",
    "status_on_publish": "draft"
  }'

For WebSocket-based real-time progress tracking (recommended for interactive applications), connect to wss://ws.aiagentssee.com/v1?token=<id_token> and send a subscribe message with the job ID. See the workflow documentation for details on the WebSocket protocol and event format.

CORS and Browser Requests

The API supports CORS (Cross-Origin Resource Sharing) for browser-based integrations. Allowed origins include your configured custom domains and localhost for development. All endpoints return appropriate CORS headers including Access-Control-Allow-Origin, Access-Control-Allow-Headers, and Access-Control-Allow-Methods. Preflight OPTIONS requests are handled automatically by the API Gateway.

Related Documentation

• Webhook Setup — Get push notifications instead of polling.
• Google Search Console — Connect Google data to the API.
• Security Overview — API security and encryption details.