REST API Reference

Base URL

All API requests are made to your WordPress site's REST API namespace. Replace yoursite.com with your actual domain.

https://yoursite.com/wp-json/tamrank/v1/

Authentication

The TamRank API requires authentication for all requests. Two methods are supported.

Application Passwords (recommended)

WordPress 5.6+ supports Application Passwords natively. Go to Users > Profile > Application Passwords in your WordPress admin to generate one. Use HTTP Basic Auth with your WordPress username and the generated application password.

curl https://yoursite.com/wp-json/tamrank/v1/meta/42 \
  -u "admin:XXXX XXXX XXXX XXXX XXXX XXXX"

Cookie + Nonce

If you are making requests from within the WordPress admin (for example, from a custom plugin page), you can authenticate using the built-in cookie and nonce. Pass the nonce as a header or query parameter.

fetch('/wp-json/tamrank/v1/meta/42', {
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
})

Retrieve all SEO metadata for a single post, page, or custom post type. Returns both Free and PRO fields regardless of license. The response always includes every field.

Example Request

curl https://yoursite.com/wp-json/tamrank/v1/meta/42 \
  -u "admin:XXXX XXXX XXXX XXXX XXXX XXXX"

Example Response

{
  "id": 42,
  "meta_title": "How to Improve Core Web Vitals in WordPress",
  "meta_description": "Learn practical steps to optimize LCP, FID, and CLS scores on your WordPress site.",
  "focus_keyword": "core web vitals wordpress",
  "custom_slug": "improve-core-web-vitals-wordpress",
  "noindex": false,
  "nofollow": false,
  "social_title": "Core Web Vitals Guide for WordPress",
  "social_description": "Step-by-step guide to passing Core Web Vitals on WordPress.",
  "social_image": "https://yoursite.com/wp-content/uploads/cwv-guide-og.jpg",
  "canonical_url": "",
  "schema_auto_type": "Article",
  "schema_auto_extras": [],
  "secondary_keywords": [
    "page speed optimization",
    "wordpress performance"
  ],
  "secondary_keywords_enabled": true
}

Response Fields

Create or update SEO metadata for a single post. Partial updates are supported: send only the fields you want to change. Omitted fields remain untouched.

Fields

Example Request

curl -X POST https://yoursite.com/wp-json/tamrank/v1/meta/42 \
  -u "admin:XXXX XXXX XXXX XXXX XXXX XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "meta_title": "How to Improve Core Web Vitals in WordPress",
    "meta_description": "A practical guide to optimizing LCP, FID, and CLS.",
    "focus_keyword": "core web vitals wordpress",
    "noindex": false
  }'

Example Response

{
  "id": 42,
  "updated": true,
  "fields_updated": [
    "meta_title",
    "meta_description",
    "focus_keyword",
    "noindex"
  ],
  "pro_fields_skipped": []
}

Free User Response (with PRO fields)

When a Free user sends PRO-only fields, those fields are skipped and listed in the response:

{
  "id": 42,
  "updated": true,
  "fields_updated": [
    "meta_title",
    "focus_keyword"
  ],
  "pro_fields_skipped": [
    "social_title",
    "canonical_url"
  ]
}

Update SEO metadata for multiple posts in a single request. Each item in the array follows the same schema as the single POST endpoint. Results are returned per post, with individual success or error status.

Example Request

curl -X POST https://yoursite.com/wp-json/tamrank/v1/meta/batch \
  -u "admin:XXXX XXXX XXXX XXXX XXXX XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "post_id": 42,
        "meta_title": "Updated Title for Post 42",
        "focus_keyword": "core web vitals"
      },
      {
        "post_id": 87,
        "meta_title": "SEO Guide for Beginners",
        "meta_description": "Everything you need to know about on-page SEO.",
        "noindex": false
      },
      {
        "post_id": 9999,
        "meta_title": "This Post Does Not Exist"
      }
    ]
  }'

Example Response

The response contains a results array. Each entry shows the outcome for that post. Failures do not block other items from being processed.

{
  "results": [
    {
      "post_id": 42,
      "updated": true,
      "fields_updated": ["meta_title", "focus_keyword"]
    },
    {
      "post_id": 87,
      "updated": true,
      "fields_updated": ["meta_title", "meta_description", "noindex"]
    },
    {
      "post_id": 9999,
      "error": "rest_post_invalid_id",
      "message": "Invalid post ID."
    }
  ],
  "total": 3,
  "succeeded": 2,
  "failed": 1
}

Limits

• Maximum 50 items per batch request
• PRO license required (Free users receive a 403 error)
• Rate limited to 5 requests per minute

Schema Markup

TamRank supports automatic schema detection and manual schema templates. The automatically detected schema fields are available via the API.

Supported Schema Types

Extra schema types (can be combined with a main type): FAQPage, VideoObject, HowTo, ImageObject

API Fields

Auto-detection vs. API

• Auto-detection (PRO): TamRank analyzes your page content and picks the best schema type. Stored in schema_auto_type and schema_auto_extras.
• Via the API (PRO): You can override schema_auto_type and schema_auto_extras manually. Useful for bulk updates or when you want full control.
• Manual templates: Advanced schema templates with custom field mappings are managed in WordPress admin and are not currently available via the API.

Example: Set schema via API

curl -X POST -u "user:app-password" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_auto_type": "Product",
    "schema_auto_extras": ["FAQPage"]
  }' \
  https://yoursite.com/wp-json/tamrank/v1/meta/42

Rate Limiting

Every API response includes rate limit headers so you can track your usage.

Response Headers

X-RateLimit-Limit

Maximum number of requests allowed in the current window

X-RateLimit-Remaining

Number of requests remaining in the current window

X-RateLimit-Reset

Unix timestamp when the rate limit window resets

Rate Limits by Tier

429 Response Example

When you exceed the rate limit, the API returns a 429 status code with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 34
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711296000

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 34 seconds.",
  "data": {
    "status": 429
  }
}

Error Codes

The API uses standard HTTP status codes. Error responses include a code field for programmatic handling and a human-readable message.

Error Response Format

{
  "code": "rest_invalid_param",
  "message": "meta_title exceeds the maximum length of 120 characters.",
  "data": {
    "status": 400,
    "params": {
      "meta_title": "Must be 120 characters or fewer."
    }
  }
}

Validation

All input is validated and sanitized before saving. Here is what to expect.

• Text fields are stripped of HTML tags to prevent injection
• Descriptions preserve line breaks (\n) but strip all HTML
• URLs (social_image, canonical_url) are validated for proper format
• Booleans accept true/false, 1/0, or "yes"/"no"
• Field lengths are checked against the maximum before saving (see the fields table above)
• secondary_keywords accepts a maximum of 5 items in the array