docs: add ttl

data/introspection.json

@@ -397,7 +397,7 @@
       {
         "kind": "SCALAR",
         "name": "Int",
-        "description": "The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. ",
+        "description": "The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.",
         "fields": null,
         "inputFields": null,
         "interfaces": null,

src/pages/docs/api/api-basics/cache.md

@@ -2,9 +2,9 @@
 title: Cache
 ---
 
-We have a builtin caching layer for speed up consecutive API calls with the same query parameters.
+We have a builtin caching layer for speed up consecutive API calls based on query parameters.
 
-First time you query for a resource that not was previously served, we will create it, what is known as cache *MISS*.
+The first time you query for a resource that not was previously served, it will be created, what is known as cache **MISS**.
 
 The cache status is reflected using the response header as `x-cache-status`.
 
@@ -21,7 +21,7 @@ module.exports = async () => {
   }} 
 />
 
-The successive requests for the resource will consume the cached version of the resource, what is known as cache *HIT*.
+The successive requests for the resource will consume the cached version of the resource, what is known as cache **HIT**.
 
 <MultiCodeEditor languages={{
   Shell: `microlink-api https://www.reddit.com | grep -i "x-cache-status"`,
@@ -36,11 +36,9 @@ module.exports = async () => {
   }} 
 />
 
-The period of time the resource is cached is known as *Time To Live* (TTL) and it is fixed to **1 hour**.
+The period of time the resource is cached is known as **Time To Live** ([ttl](/docs/api/api-parameters/ttl)) and it specifies the maximum quantity of time the resource will served from cache. 
 
-That means, every 1 hour the cached response copy is invalidated and will generate a new one in the next API call.
-
-You can see the TTL value in a human friendly way as `x-cache-expired-at` in the reponse headers.
+You can see the remain time before [ttl](/docs/api/api-parameters/ttl) expiration as `x-cache-expired-at` in the reponse headers.
 
 <MultiCodeEditor languages={{
   Shell: `microlink-api https://www.reddit.com | grep -i "x-cache-expired-at"`,
@@ -55,6 +53,6 @@ module.exports = async () => {
   }} 
 />
 
-It's reflected as `cache-control` as well to tell browsers how much time they can serve the same resource until cache expiration.
+Also, [ttl](/docs/api/api-parameters/ttl) is properly reflected as `cache-control` response header to tell browsers how much time they can serve the same resource until refresh it.
 
-If you want to bypass and get a fresh response, you can use [force](/docs/api/api-parameters/force) for regenerating the cache copy without waiting TTL expiration time.
+If you want to bypass and get a fresh response, you can use [force](/docs/api/api-parameters/force) for regenerating the cache copy without waiting [ttl](/docs/api/api-parameters/ttl) expiration time.

src/pages/docs/api/api-parameters/ttl.md

@@ -0,0 +1,32 @@
+---
+title: 'ttl'
+--- 
+
+> This feature is only for pro plans.
+
+Type: `number`<br/>
+Default: `3600000`<br/>
+
+It establishes the maximum quantity of time a resource served from cache layer is considered as valid.
+
+The value provided need to be at least **1 hour** and not higher than **24 hours**, specified in milliseconds.
+
+The idea behind exposing this API parameter is to optimize better how much time the target URL can be cached:
+
+- If you are targetting an URL that changes very often and response time is not critical for you, a small value will work better.
+- If you are targetting an URL that doesn't change too much or you want to maximize cache hits, getting faster response time, a higher value works better.
+
+The value provided will reflected as `x-cache-ttl` as part of the response headers
+
+<MultiCodeEditor languages={{
+  Shell: `microlink-api https://www.twitter.com/microlinkhq | grep -i "x-cache-ttl"`,
+  'Node.js': `const mql = require('@microlink/mql')
+ 
+module.exports = async () => {
+  const { status, data, response } = await mql('https://www.reddit.com')
+  
+  console.log(response.headers.['x-cache-ttl' ) // => '3h 56m 35.2s'
+}
+  `
+  }} 
+/>

src/templates/doc.js

@@ -162,6 +162,10 @@ const ROUTES_API = [
         name: 'url',
         href: '/docs/api/api-parameters/url'
       },
+      {
+        name: 'ttl',
+        href: '/docs/api/api-parameters/ttl'
+      },
       {
         name: 'prerender',
         href: '/docs/api/api-parameters/prerender'