Sera API¶

An on-demand API can be used to submit page URLs to SERA for rendering, allowing you to integrate with tools and automatically render frequently updated sites via scripts or tools.

Prerequisite¶

You must have an account on Nitrogen.
Your target domain on which you want to call SERA on demand api must have been registered on Nitrogen.
You must have a service account configured with Editor access. If not, you can refer this article for the same.

Render API Request¶

Render API Request Details¶

Method :
- PUT
Endpoint :
- https://dash.n7.io/api/v2/sera/domains/{domain}/ondemand/render
Request Headers :
- Authorization: Token <api-key-of-service-account>

Request Payload :

{
    "pageGroupName": "Saree Category",
    "urls": [
        "https://www.example.com/saree/satin-sarees",
        "https://www.example.com/saree/shimmer-sarees",
        "https://www.example.com/saree/silk-sarees",
        "https://www.example.com/saree/supernet-sarees",
        "https://www.example.com/saree/tissue-sarees"
    ]
}

Note: These are the mandatory parameters. Please check the next section for all the available parameters.

Render API Request Explanation¶

Path params :
- domain: the domain for which urls needs to be rendered

Payload Params :

Field	Description	Mandatory	Default	Note
`urls`	List of URLs that needs to be rendered	mandatory	-	You can process a maximum of 100 URLs at a time
`pageGroupName`	Name of the page group set in Dash	optional	`Just-In-Time`	-
`viewport`	Page to be rendered for which Device viewport (Desktop/Mobile/Both)	optional	`SERA_VIEWPORT_DESKTOP_MOBILE`	`SERA_VIEWPORT_DESKTOP`, `SERA_VIEWPORT_MOBILE`, `SERA_VIEWPORT_DESKTOP_MOBILE`
`resourceBlockRegex`	List of request-url regexes that need to blocked during rendering	optional	-	eg: images and third-party calls usually not required for non-user traffic.
`pageWaitTimeout`	The time the SERA rendering process should wait before responding with timeout error	optional	`30`	-
`stabilizeWaitTimeout`	Extra time required for rendering to complete after page load	optional	`0`	-
`waitForSelector`	Process till the given selector appears on page	optional	-	-
`blockingSelectors`	List of element selectors that need to removed from the rendered page	optional	-	-
`htmlBlockingRegex`	List of element regexes that need to removed from the rendered page	optional	-	-
`callbackUrl`	A Url which will be called upon the rendering of the pages with the relevant details	optional	-	Details are given in next section

Render API Request Example¶

curl --request PUT --location 'https://dash.n7.io/api/v2/sera/domains/{domain}/ondemand/render' \
--header 'Authorization: Token <api-key-of-service-account>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pageGroupName": "Sarees",
    "urls": [
        "https://www.example.com/sarees/all",
        "https://www.example.com/sarees/new",
        "https://www.example.com/sarees/sale",
        "https://www.example.com/sarees/cotton",
        "https://www.example.com/sarees/silk",
        "https://www.example.com/sarees/georgette"
    ],
    "viewport": "{SERA_VIEWPORT_DEVICE}",
    "resourceBlockRegex": [
        ".+\\.(jpg|jpeg|png|gif|webp|avif|svg|mp3|mp4|mov|ogg|webm|wav|mpeg|woff|woff2|ttf|eot|otf)(\\?.*|&.*|$)",
        "^data:image/.+"
        "/(www.google.com/pagead|www.google.com/ccm|www.google.com/maps|www.google-analytics.com|analytics.google.com|pagead2.googlesyndication.com|www.google.co.in/pagead|www.google.co.in/ads|www.facebook.com/tr|www.facebook.com/privacy_sandbox/pixel|connect.facebook.net/signals|.*.doubleclick.ne|.*.clarity.mst|.*.googleapis.com)/"
    ],
    "pageWaitTimeout": 30,
    "stabilizeWaitTimeout": 10,
    "waitForSelector" : "div.userDetails p.userIdVal",
    "blockingSelectors": [
        "#sale-popup",
        "div.whatsAppFloat"
    ],
    "htmlBlockingRegex": [
        "<video[^>]>([\s\S]?)</video>"
    ],
    "callbackUrl" : "https://www.example.com/callbacks/sera"
}'

Render API Response¶

Render API Response Example¶

{
    "message": "905aebcc-32ed-4c77-96e9-d048276a1819"
}

Render API Response Explanation¶

Here,

message : Unique UUID, to identify the URLs requested in SERA API

Callback API Response¶

The callback URL is invoked with an HTTP POST request, containing the following payload

Callback API Response Details¶

Response Method : POST
Response headers :
- Content-Type : application/json
- user-agent : Nitrogen/1.0 SERA Callback

Response Body :

{
    "runId" : "{uuid}",
    "domain" : "{domain-name}",
    "startTime" : "{timestamp}",
    "endTime" : "{timestamp}",
    "url" : "{url}",
    "statusCode" : {render-status},
    "deviceType" : "{SERA_VIEWPORT_DEVICE}"
}

Callback API Response Explanation¶

runId : message recieved in response from SERA API,
domain : www.example.com,
startTime : start timestamp for url processing in UTC,
endTime : end timestamp for url processing in UTC,
url : https://www.example.com/saree/satin-sarees,
statusCode : Status code received from origin
deviceType : device type for which URL is requested

Callback API Response Example¶

{
    "runId" : "905aebcc-32ed-4c77-96e9-d048276a1819",
    "domain" : "www.example.com",
    "startTime" : "2024-10-15T08:31:26.857Z",
    "endTime" : "2024-10-15T08:31:52.182Z",
    "url" : "https://www.example.com/saree/satin",
    "statusCode" : 200,
    "deviceType" : "desktop"
}