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. Responses are JSON-encoded.

Authentication

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

Base URL

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

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

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"
}

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.

Code Examples for Common Operations

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.