Adds an additional domain
siteId required | string Site ID |
domain | string The domain that should be added. For ex. example.com |
{- "domain": "example.com"
}
{- "message": "Domain: example.com was added."
}
Remove a domain from the additional domains list
siteId required | string Site ID |
domain | string The domain that should be removed. For ex. example.com |
{- "domain": "example.com"
}
{- "message": "Domain: example.com was removed."
}
siteId required | string Site ID |
layout required | string A (design) layout identifier. Critical CSS is generated only once per layout. Use this parameter to create separate critical CSS for the different page layouts on your site. For example your home page would be typically layed out in a different way compared to your product pages for example. You can use a "home" layout string for the home page and "product" for all your product pages. Avoid using unique layout identifiers for each URL though, as this will increase the time needed to prepare an optimized cache file for the requested URL. |
X-Nitro-Url required | string The URL that you are requesting cache for |
X-Nitro-Visitor-Addr | string The IP of the visitor that triggered this call to /cache/get. We will forward this IP through X-Forwarded-For header when fetching the requested URL |
X-Nitro-Cache-Prefix | string A custom cache prefix. Use this when you need to divide the cache based on custom rules for your platform. For example, if you serve different content based on the visitor's location, you can add the country, continent, language, etc. as a prefix. |
X-Nitro-Ajax | string Indicate whether we should request this URL via AJAX |
X-Nitro-Priority | string Use this to schedule an optimization with low priority. The only possible value for this parameter is "LOW". |
X-Nitro-Loopback | string If this header is present NitroPack will bypass DNS records and connect directly to the IP calling this method. |
Deletes the cache files stored on our servers and removes tag associations. If a URL is specified only cache files for this URL are deleted and only the tag associations with this URL are removed. This operation frees disk space.
siteId required | string Site ID |
url | string A specific URL that you would like to purge cache for. |
tag | string A specific tag that you would like to purge cache for. If this is provided it takes precedence over the url parameter and the API will return a list of the purged URLs. The returned list contains up to 250 purged URLs, so you may need to keep repeating this request until the returned list contains no items. |
pagecache_only | boolean If true only page cache files will be purged. Otherwise, the entire cache is deleted included stored assets. |
light_purge | boolean If true it will preserve images from being deleted. If pagecache_only is true this will be ignored. |
reason | string The purge reason, in human-readable form. |
{- "url": "string",
- "tag": "string",
- "pagecache_only": true,
- "light_purge": true,
- "reason": "string"
}
""
Returns information about the last /cache/purge request for the site identified by siteId
siteId required | string Site ID |
{- "timestamp": "1549618432",
- "tag": "route:common:home",
- "reason": "Product update"
}
Returns a challenge to be solved on your end. You need to get and solve one of these challenges, then provide the result in the request to /config/get. This is needed in order to verify that we serve your config to your applications only. Any request to /config/get that does not provide a challnegeId and a valid solution will be rejected.
The API offers a way to retrieve the configuration file, which contains the settings edited through the administrative dashboard. In order to obtain the configuration, the API client must prove that it holds the site secret. To do this the client must provide a response to a challenge issued by the API server. The API server would never ask for the client to send the plaintext site secret over the network, nor would it ever send the secret to the client.
Challenges are 128 random bytes encoded as lowercase hex digits resulting in a 256 character string. The response to a challenge is calculated using the following formula: sha512(sha512(sha512(sha512(sha512(secret + challenge))))) Or in other words, first concatenate the site secret and challenge strings (in that order), then apply the sha512 hashing algorithm to the combined string 5 times. The result of the last hashing is the challenge response.
Below are the steps that must be carried out to receive and answer a challenge:
First the API client makes an HTTP GET request to https://api.getnitropack.com/config/getchallenge/:site_id
The API will return a JSON structure as follows:
{
"cid": "...", // Challenge ID (64 character string)
"sc0": "...", // Server challenge 0 (256 character string)
"sc1": "...", // Server challenge 1 (256 character string)
"resp": "..." // Response to server challenge 0 (128 character string)
}
The challenge ID is to be submitted along with the challenge response. Server challenge 0 is used for the client to verify that the challenge came from the API server. The client should calculate the expected response for server challenge 0 using the site secret and the formula above and compare the result with the "resp" key using a cryptographically secure string comparison algorithm (ex. PHP's hash_equals function).
If this comparison fails, the client should terminate its attempt to fetch the configuration and notify the administrator managing the site running the client.
Once the client has established that the challenge came from the API server, it can proceed with calculating the response to server challenge 1, again using the site secret and the formula above.
Then the client should make a second HTTP GET request, this time to https://api.getnitropack.com/config/get/:site_id where :site_id matches the :site_id from the first request. This request should include two additional headers: X-Challenge-ID: The challenge ID from the JSON response of the previous request X-Challenge-Response: The challenge response calculated from Server challenge 1
The response to this request will always be JSON formatted. If the challenge response was correct, then the response will have an HTTP status 200 and the body will contain the configuration for the given :site_id. If something went wrong, then the response will have an HTTP status 403 and the body will be {"error":"Invalid request"}
Note that by design the API will return the same error with no specific explanation for all issues, including wrong a site_id, wrong or expired challenge id, or incorrect challenge response.
Challenges expire 30 seconds after they are created, after which even a correct challenge response will not be accepted.
siteId required | string Site ID |
{- "cid": "...",
- "sc0": "...",
- "sc1": "...",
- "resp": "..."
}
Returns the config, for the site identified by siteId, as a JSON encoded string
siteId required | string Site ID |
X-Challenge-Id required | string The challenge ID that was provided to you by /config/getchallenge |
X-Challenge-Response required | string The challenge response calculated from Server Challenge 1 provided to you by /config/getchallenge |
{ }
Add excluded url for the given website
siteId required | string Site ID |
url_pattern | string |
{- "url_pattern": "*excluded-pattern*"
}
{- "error": "Invalid request"
}
Remove excluded url for the given website
siteId required | string Site ID |
url_pattern | string |
{- "url_pattern": "*excluded-pattern*"
}
{- "error": "Invalid request"
}
Get a subsetted version of fonts for a given URL
siteId required | string Site ID |
X-Nitro-Url required | string The URL that you want fonts subsetted for |
X-Nitro-Device required | string The device type to use when loading the URL. Should be one of the following: desktop, mobile, tablet |
{- "fonts": {
- "font_source_url": "font_optimized_url"
}, - "glyphs": [
- "glyph1",
- "glyph2",
- "glyph3"
]
}
Returns an array with the Html, CSS, JS and Image savings in bytes along with a total.
siteId required | string Site ID |
{- "html": 0,
- "css": 11245243,
- "js": 88234014,
- "image": 234702347,
- "total": 334181604
}
Returns the disk usage on our storage servers in bytes
siteId required | string Site ID |
{- "diskUsage": 334181604,
- "freeSpace": 983240,
- "diskUsageHtml": 4181604,
- "diskUsageCss": 34181604,
- "diskUsageJs": 181604,
- "diskUsageFont": 81604,
- "diskUsageImage": 330181604
}
Returns the number of optimization requests that have been made and the maximum number of requests included in your billing plan.
siteId required | string Site ID |
{- "count": 250,
- "maxCount": 5000
}
Assigns the provided tags to the provided URL. You can later use tags to performs operations like purging the cache for all URLs tagged by a certain tag name.
siteId required | string Site ID |
url required | string A URL that you would like to tag |
tag required | string A tag name that you wish to assign to the URL. Multiple tag names can be separated with a comma(,). Tag names must match the following pattern: /^[a-zA-Z0-9:]+$/ and be no longer than 128 chars |
{- "tag": "apple,iphone"
}
{- "success": true
}
Unassigned the provided tags from the provided URL
siteId required | string Site ID |
url | string A URL that you would like to remove a tag from. If not provided the tag will be removed from all URLs |
tag required | string A tag name that you wish to unassigned from the URL. You can use wildcards (*) to remove more than one tags in one go. |
{- "tag": "apple,iphone"
}
{- "removed": 3
}
Returns a list of URLs that have been tagged with the provided tag name. The responses are paginated including up to 250 results per page. The response code will be 404 if no matches have been found.
siteId required | string Site ID |
tagName required | string A tag name that you wish to get URLs for. You can use wildcards (*) to match multiple tags. For example "apple:*" will match both "apple:iphone" and "apple:macbook". |
page required | string The page number that you need results for. The first page number is 1. |
limit required | string Change the default limit of 250 to a custom value. Max value is still 250 though. |
[- {
- "tags": [
- "apple"
], - "deviceType": "desktop",
- "lastOptimizedDate": "2018-09-0504:51:13",
- "statusCode": 200
}
]
Returns a count of URLs that have been tagged with the provided tag name.
siteId required | string Site ID |
tagName required | string A tag name that you wish to get URLs for. You can use wildcards (*) to match multiple tags. For example "apple:*" will match both "apple:iphone" and "apple:macbook". |
{- "count": 12
}
Returns a list of all tags assigned to the queried url.
siteId required | string Site ID |
page required | integer The page number that you need results for. The first page number is 1. |
limit required | integer Change the default limit of 250 to a custom value. Max value is still 250 though. |
url | integer The url for which you wish to get tags for. This parameter should be encoded as url. |
"[\"apple\"]"
Returns a paginated list of urls assigned to the site. Each page can contain up to 250 result entries |
siteId required | string Site ID |
page required | integer The page number that you need results for. The first page number is 1. |
limit required | integer The page number that you need results for. The first page number is 1. |
search | string Use this to filter URLs matching a pattern. Wildcards (*) are allowed. |
deviceType | string Use this to filter URLs by device type. Accepted values are "desktop", "tablet", "mobile" and "none". If "none" is used, the results will include URLs that have only been tagged, but not optimized. |
status | string Use this to filter URLs by status. Accepted values are all statuses described at the end of this document. To get URLs which are still pending for optimization use status -1. |
[- {
- "tags": [
- "apple",
- "phone"
], - "deviceType": "desktop",
- "lastOptimizedDate": "2018-09-0504:51:13",
- "statusCode": 200
}
]
Returns the number of optimized URLs. Does not take cache expiration into account, it simply returns the number of unique URLs that we have logged due to optimization requests or tagging.
siteId required | string Site ID |
search | string Use this to filter URLs matching a pattern. Wildcards (*) are allowed. |
deviceType | string Use this to filter URLs by device type. Accepted values are "desktop", "tablet", "mobile" and "none". If "none" is used, the results will include URLs that have only been tagged, but not optimized. |
status | string Use this to filter URLs by status. Accepted values are all statuses described at the end of this document. To get URLs which are still pending for optimization use status -1. |
{- "count": 256
}
Returns a paginated list of urls waiting to be optimized. Each page can contain up to 250 result entries.
siteId required | string Site ID |
page required | string The page number that you need results for. The first page number is 1. |
limit required | string Change the default limit of 250 to a custom value. Max value is still 250 though. |
priority | string If present, information about the specified priority queue will be used. Possible values are: "low" |
[
]
Returns the number of cache variations that are pending (can be more than the number of URLs).
siteId required | string Site ID |
priority | string If present, information about the specified priority queue will be used. Possible values are: "low" |
{- "count": 256
}
Unset a variation cookie by providing its name.
siteId required | string Site ID |
name | string The name of the variation cookie. |
{- "name": "notification_popup"
}
{- "error": "Invalid request"
}
Set a variation cookie by providing its name and, optionally, appropriate values. Variation cookies are used for generating unique cached pages for a different combination of cookies. The optional values are used by the Cache Warmup service.
siteId required | string Site ID |
name | string The name of the variation cookie. |
value | string Optional possible values for this cookie (comma-separated). |
group | integer Optional group of this cookie. Must be a positive integer. This attribute is used to group different cookies for the purposes of Cache Warmup. If group is not provided, the cookie will be accepted, and will not belong to any group. |
{- "name": "language",
- "value": "en,de,es"
}
{- "error": "Invalid request"
}
Set a home page URL for the given webite. The links found in the home page will be crawled on events like cache purge. (If SiteMap XML is configured it takes precedence over this setting)
siteId required | string Site ID |
url | string Your home page URL. If this parameter is not present in the request, the call to this endpoint works as unset. |
{
}
{- "error": "Invalid request"
}
Set a sitemap URL for the given website. The sitemap URL must be publicly accessible and formatted in the SiteMap XML format. The links found in this sitemap will be crawled on events like cache purge.
siteId required | string Site ID |
url | string Your publicly accessible sitemap URL. If not present the call to this endpoint works as unset. |
{
}
{- "error": "Invalid request"
}
Estimate how many optimizations will be used for cache warmup using the current settings.
siteId required | string Site ID |
id required | string Leaving this parameter empty will start a new estimation process. Passing an ID will return the result of the estimation. If NitroPack is still estimating the returned number will be -1. Estimation results expire in 1h. |
urls | string A list of URLs to be warmed up. If empty or not set the home page links or the entire sitemap list (if configured) will be warmed up. |
{
}
{- "count": 1432
}
Run cache warmup for the given website.
siteId required | string Site ID |
urls | string A list of URLs to be warmed up. If empty or not set the home page links or the entire sitemap list (if configured) will be warmed up. |
{
}
{- "error": "Invalid request"
}
Set a webhook URL for the given website. The webhook URL must be publically accessible, as the API will call it on specific events:
siteId required | string Site ID |
type required | string The type of the webhook. Allowed values: "config", "cache_clear", "cache_ready", "sitemap" |
url | string Your publically accessible webhook URL. |
{- "type": "config",
}
{- "error": "Invalid request"
}
Get a webhook URL for the given webite.
siteId required | string Site ID |
type required | string The type of the webhook. Allowed values: "config", "cache_clear", "cache_ready", "sitemap" |
{- "error": "Invalid request"
}