SEO Master Pro API Documentation

Build powerful SEO applications with our comprehensive RESTful API

Getting Started

The SEO Master Pro API allows you to programmatically access and manage all your SEO data. Our API is organized around REST, uses JSON-encoded requests and responses, and standard HTTP response codes.

Real-Time Data

Access real-time SEO metrics and rankings

Secure & Reliable

Enterprise-grade security with 99.9% uptime

RESTful Design

Clean, predictable API design patterns

Base URL

https://api.seomasterpro.com/v1

Authentication

All API requests require authentication using JWT Bearer tokens. Include your access token in the Authorization header of each request.

Obtaining an Access Token

First, obtain an access token by sending a POST request to the login endpoint:

POST /auth/login

{
  "email": "user@example.com",
  "password": "your_password",
  "tenantSubdomain": "your_subdomain"
}

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "admin"
  },
  "tenant": {
    "id": "uuid",
    "subdomain": "your_subdomain",
    "plan": "professional"
  }
}

Using the Access Token

Include the access token in the Authorization header of all API requests:

Request Headers

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

API Endpoints

Clients

GET /tables/clients

List all clients with pagination

Query Parameters

`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 100)
`search`	string	Search query
`sort`	string	Sort field (e.g., "name", "created_at")

Example Request

curl https://api.seomasterpro.com/v1/tables/clients?page=1&limit=10 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (200 OK)

{
  "data": [
    {
      "id": "uuid",
      "tenant_id": "uuid",
      "name": "Acme Corporation",
      "website_url": "https://acme.com",
      "industry": "ecommerce",
      "status": "active",
      "created_at": 1704067200000,
      "updated_at": 1704067200000
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 10,
  "table": "clients",
  "schema": {...}
}

GET /tables/clients/{id}

Get a specific client by ID

POST /tables/clients

Create a new client

Request Body

{
  "name": "New Client",
  "website_url": "https://newclient.com",
  "industry": "saas",
  "status": "active"
}

PUT /tables/clients/{id}

Update an existing client (full update)

PATCH /tables/clients/{id}

Partially update a client

DELETE /tables/clients/{id}

Delete a client (soft delete)

Keywords

GET /tables/keyword_rankings

List all keyword rankings with pagination

Response (200 OK)

{
  "data": [
    {
      "id": "uuid",
      "tenant_id": "uuid",
      "client_id": "uuid",
      "keyword": "seo tools",
      "search_engine": "google",
      "location": "United States",
      "position": 3,
      "previous_position": 5,
      "url": "https://example.com/page",
      "search_volume": 5400,
      "created_at": 1704067200000
    }
  ],
  "total": 247,
  "page": 1,
  "limit": 100
}

POST /tables/keyword_rankings

Add new keyword for tracking

Analytics

GET /tables/client_performance_metrics

Get performance metrics for clients

GET /tables/seo_audit_results

Get SEO audit results

Reports

POST /api/reports/generate

Generate a new report

Request Body

{
  "client_id": "uuid",
  "report_type": "monthly",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "format": "pdf"
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure:

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing authentication token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: client_id",
    "details": {
      "field": "client_id",
      "reason": "required"
    }
  }
}

Rate Limiting

API rate limits vary by plan:

Plan	Requests per minute	Requests per day
Starter	60	10,000
Professional	120	50,000
Enterprise	Unlimited	Unlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704067200

Webhooks

Set up webhooks to receive real-time notifications about events in your account:

Available Events

client.created - New client added
client.updated - Client updated
keyword.ranking_changed - Keyword ranking changed significantly
audit.completed - SEO audit completed
report.generated - Report generated

Webhook Payload

{
  "event": "keyword.ranking_changed",
  "timestamp": 1704067200000,
  "data": {
    "keyword_id": "uuid",
    "keyword": "seo tools",
    "previous_position": 5,
    "current_position": 3,
    "change": 2
  }
}