Cache Invalidation API Guide

This guide explains how to use Optimole's API endpoints to invalidate cache and generate cache tokens for your images.

Base URL

All API requests should be made to:

https://dashboard.optimole.com/api/optml/v2/cache

Authentication

All API requests require authentication using your Optimole API keys.

For detailed instructions on how to authenticate with the Optimole API, please refer to our Authentication Documentation. There you'll find information on:

• How to obtain your API keys
• How to include authentication headers in your requests
• Authentication best practices

Cache Invalidation Endpoints

1. Invalidate Cache

This endpoint allows you to invalidate (clear) the cache for different scopes of images.

Endpoint: POST /invalidate/{type}

Where {type} can be one of:

• all - Invalidate all cached images
• domain - Invalidate cached images for a specific domain
• asset - Invalidate cached images for specific assets/URLs

Examples

Invalidate All Cache:

POST /api/optml/v2/cache/invalidate/all

Invalidate Domain Cache:

POST /api/optml/v2/cache/invalidate/domain
Content-Type: application/json

{
  "domain": "example.com"
}

Invalidate Specific Assets:

POST /api/optml/v2/cache/invalidate/asset
Content-Type: application/json

{
  "assets": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.png",
    "7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p"  // You can use asset hashes too
  ]
}

Notes:

• When invalidating assets, you can use either the full URL of the image or the 32-character asset hash
• You can invalidate up to 100 assets in a single request

2. Request Cache Token

This endpoint generates a new cache token that you can use as a cache buster in your image URLs.

Endpoint: POST /token

Example

POST /api/optml/v2/cache/token

Response

{
  "success": true,
  "data": {
    "token": "abc123xyz789"
  }
}

Using Cache Tokens

When to Generate a Token vs. Using a Random String

• Use an API-generated token when: You've updated an image on your origin server and need Optimole to fetch the new version instead of using its cached copy
• Use any random string when: You want to serve a fresh version of an already optimized image from Optimole's CDN to end users

Once you have a cache token (either generated or random), you can add it to your image URLs to control caching behavior:

Method 1: URL Parameter

Add the token as a cb parameter in your Optimole URL:

https://your-domain.optimole.com/cb:abc123xyz789/w:100/https://example.com/image.jpg

Method 2: Optimole PHP SDK

Use the cache buster method in the Optimole PHP SDK:

use Optimole\Sdk;

$optimole = new Sdk\Optimole();
$optimole->setCacheBuster('abc123xyz789');
$optimoleUrl = $optimole->getUrl('https://example.com/image.jpg');

For more details on the SDK, visit: https://github.com/Codeinwp/optimole-php-sdk

Error Handling

The API may return the following errors:

• User not found: The account associated with the API key doesn't exist
• User not active: The account is not active
• Too many assets to invalidate: You've exceeded the 100 asset limit