Authenticated API reference

Overview

The SEO4Ajax authenticated API is organized around REST. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. It uses built-in HTTP features, HTTP verbs and HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, excluding errors.

Authentication

You authenticate to the SEO4Ajax API by providing your secret API key in the request. You can find your API key in your account settings. Your API key carry many privileges, so be sure to keep it secret! Authentication to the API occurs via the HTTP header X-Api-Key. You must authenticate for all requests and provide your API key as the value of this header. All API requests must be made over HTTPS, calls made over plain HTTP will fail.

Errors

The SEO4Ajax API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with SEO4Ajax's servers. The content of the body returned with an error contains a more detailed message about the error.

HTTP Status Code Summary

200 - OK

Everything worked as expected.

400 - Bad Request

Often missing a required parameter or providing an invalid parameter.

401 - Unauthorized

No valid API key provided.

404 - Not Found

The requested resource doesn't exist.

500, 502, 503, 504 - Server Errors

Something went wrong on SEO4Ajax's end.

Pagination

Some SEO4Ajax API resources have support for bulk fetches. For instance you can list sites, captures, errors, pending captures and capture logs.

Page based

Except for listing capture logs, these list API methods share a common structure. SEO4Ajax utilizes a page number based pagination, using the parameter page.

Arguments

limit optional, default to 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

page optional, default to 1

The page number to be returned.

Cursor based

For listing capture logs, SEO4Ajax utilizes cursor-based pagination, using the parameter startAfter. Pass startAfter to dictate where in the list you would like to begin.

Arguments

limit optional, default to 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

startAfter optional

A cursor for use in pagination. startAfter is a path that defines your place in the list. This parameter should be URL encoded. For instance, if you make a list request and receive 10 objects, ending with the path "/foo/bar", your subsequent call can include startAfter=%2Ffoo%2Fbar in order to fetch the next page of the list.

List response format

An array containing the actual response elements.

Sites

Site object

Attributes

name string

The name you gave to the site at its creation.

site-token string

The unique ID identifying the site on SEO4Ajax.

url string

The fully qualified URL of the site.

List all sites

Returns

Returns a list of sites you've previously registered in SEO4Ajax. The sites are returned in alphabetical order on their name.

Site settings

Settings object

Attributes

name string

The name you gave to the site at its creation.

site-token string

The unique ID identifying the site on SEO4Ajax.

url string

The fully qualified URL of the site.

entryPoints list of strings

The list of paths used as entry points to crawl the website.

ignoredPaths list of strings

The list of patterns matching paths which should not be crawled.

rewriteRules list of rewrite rules

The list of rewrite rules applied when a bot requests a URL or when the SEO4Ajax find new pages to be crawled in a capture.

jsRedirectEnabled boolean

The boolean specifying whether the JavaScript redirections are taken into account or not.

jsRedirectCode optional

The redirect code associated to JavaScript redirections.

emulateMobileDevice boolean

The boolean specifying whether the crawler emulates a mobile device when capturing a page or not.

filteredResourcePaths list of strings

The list of patterns matching URL resources which are blocked by the crawler when capturing a page.

captureExpiredPages boolean

The boolean specifying whether a page must be automatically recaptured or not when expired.

captureNewPages boolean

The boolean specifying whether a page must be automatically captured or not when it was never captured before.

processLinks boolean

The boolean specifying whether the links present in a page must be automatically captured or not.

userAgent string

The user-agent used by the SEO4Ajax crawler when capturing pages.

blockingCaptureUserAgents list of strings

The list of patterns matching user-agents allowed to wait for on-the-fly capture.

blockingCaptureMaxDelay number

The maximum delay, in seconds, allowed to wait for on-the-fly capture.

requestTimeout number

The maximum delay, in seconds, allowed to fetch any resources when capturing a page.

JSTimeout number

The delay, in seconds, to wait before capturing the page once they are no more pending requests.

mailQuota boolean

The boolean specifying whether an alert email is sent when the number of captures reach a certain quota.

maxQuota number

The percentage of captures with respect to the maximum captures allowed in the subscribed plan. Once this percentage is exceeded, the alert email is sent.

mailErrors boolean

The boolean specifying whether an alert email is sent when the number of capture errors reach a certain quota.

maxErrors number

The percentage of captured pages in error with respect to the total number of captured pages. Once this percentage is exceeded, the alert email is sent.

mailOffline boolean

The boolean specifying whether an alert email is sent when the SEO4Ajax probe detects that the site is not connected anymore to SEO4Ajax.

requestHeaders list of strings

The list of HTTP headers to add on every resource request when capturing a page.

language string

The language code to be used by the browser when capturing a page, as specified in the RFC 4646.

defaultExpirationPeriod number

The default expiration period of the captures, in days.

expirationPeriods list of objects

The list of objects defining regular expressions matching paths and their corresponding expiration period.

sitemaps list of strings

The list of fully qualified sitemap URLs to be crawled.

updateFBCache boolean

The boolean specifying whether a Facebook cache update is triggered when a page is captured.

Retrieve the settings of a site

Arguments

site-token required

The token of the website

Returns

The site settings if a valid token was provided, and an error otherwise.

Update the settings of a site

Arguments

site-token required

The token of the website.

Body

A JSON object containing the following keys. When a key is not set, the corresponding value is not reset.

name optional

The name of the website.

entryPoints optional

The list of paths used as entry points to crawl the website. The provided list replaces the current one.

ignoredPaths optional

The list of patterns matching paths which should not be crawled. The provided list replaces the current one.

rewriteRules optional

The list of rewrite rules applied when a bot requests a URL or when the SEO4Ajax find new pages to be crawled in a capture. The provided list replaces the current one.

jsRedirectEnabled optional

The boolean specifying whether the JavaScript redirections are taken into account or not.

jsRedirectCode optional

The redirect code associated to JavaScript redirections.

emulateMobileDevice optional

The boolean specifying whether the crawler emulates a mobile device when capturing a page or not.

filteredResourcePaths optional

The list of patterns matching URL resources which are blocked by the crawler when capturing a page. The provided list replaces the current one.

captureExpiredPages optional

The boolean specifying whether a page must be automatically recaptured or not when expired.

captureNewPages optional

The boolean specifying whether a page must be automatically captured or not when it was never captured before.

processLinks optional

The boolean specifying whether the links present in a page must be automatically captured or not.

userAgent optional

The user-agent used by the SEO4Ajax crawler when capturing pages.

blockingCaptureUserAgents optional

The list of patterns matching user-agents allowed to wait for on-the-fly capture. The provided list replaces the current one.

blockingCaptureMaxDelay optional

The maximum delay, in seconds, allowed to wait for on-the-fly capture.

requestTimeout optional

The maximum delay, in seconds, allowed to fetch any resources when capturing a page.

JSTimeout optional

The delay, in seconds, to wait before capturing the page once they are no more pending requests.

mailQuota optional

The boolean specifying whether an alert email is sent when the number of captures reach a certain quota.

maxQuota optional

The percentage of captures with respect to the maximum captures allowed in the subscribed plan. Once this percentage is exceeded, the alert email is sent.

mailErrors optional

The boolean specifying whether an alert email is sent when the number of capture errors reach a certain quota.

maxErrors optional

The percentage of captured pages in error with respect to the total number of captured pages. Once this percentage is exceeded, the alert email is sent.

mailOffline optional

The boolean specifying whether an alert email is sent when the SEO4Ajax probe detects that the site is not connected anymore to SEO4Ajax.

requestHeaders optional

The list of HTTP headers to add on every resource request when capturing a page. The provided list replaces the current one.

language optional

The language code to be used by the browser when capturing a page, as specified in the RFC 4646.

defaultExpirationPeriod optional

The default expiration period of the captures, in days.

expirationPeriods optional

The list of objects defining regular expressions matching paths and their corresponding expiration period. The provided list replaces the current one.

sitemaps optional

The list of fully qualified of sitemap URLs to be crawled. The provided list replaces the current one.

updateFBCache optional

The boolean specifying whether a Facebook cache update is triggered when a page is captured.

Site captures

Capture object

Attributes

path string

The path of the capture.

date ISO 8601 formated date

The date at which the page was captured.

userAgent string

The name of the last bot which requested this capture.

requestDate ISO 8601 formated date

The date of the last request coming from a bot for this page.

referer string

The path of the page where a link to this path was found.

redirectCode number

The redirect code for this path when it returns a redirect instead of the capture.

redirectLocation string

The redirect location for this path when it returns a redirect instead of the capture.

List captures

Arguments

site-token required

The token of the website.

limit optional default to 10

The limit on the number of objects to be returned. Limit can range between 1 and 100 items.

page optional default to 1

The page number to be retrieved.

orderBy optional default to "path"

The name of the field on which the results will be ordered. Could be "path" or "date".

from optional

The date from which capture objects will be returned.

to optional

The date to which capture objects will be returned.

desc optional default to false

The sort direction: ascending (default) or descending when true.

Returns

The array of capture objects.

Delete captures

Arguments

site-token required

The token of the website.

Body

A JSON array of paths to delete. The number of paths in the array must be less than or equal to 100.

Retrieve a capture

Arguments

site-token required

The token of the website.

path required

The URL encoded path for which you want to retrieve the HTML content.

Site errors

Error object

Attributes

path string

The path of the error.

date ISO 8601 formated date

The date at which the page was captured.

userAgent string

The name of the last bot which requested this path.

requestDate ISO 8601 formated date

The date of the last request from a bot for this page.

referer string

The path of the page where a link to this path was found.

error string

The type of error.

List errors

Arguments

site-token required

The token of the website.

limit optional, default to 10

The limit on the number of objects to be returned. Limit can range between 1 and 100 items.

page optional, default to 1

The page number to be retrieved.

orderBy optional, default to "path"

The name of the field on which the results will be ordered. Could be "path" or "date".

from optional

The date from which error objects will be returned.

to optional

The date to which error objects will be returned.

desc optional, default to false

The order on which the results will be returned.

errorType optional

The type of error which you want to list. By default, all types of error will be listed.

Returns

The array of error objects.

Delete site errors

Arguments

site-token required

The token of the website.

Body

A JSON array of paths to delete. The number of paths in the array must be less than or equal to 100.

Site pending captures

Pending capture object

Attributes

path string

The path of the pending capture.

date ISO 8601 formated date

The date at which the capture was requested.

state string

The state of the pending capture.

priority number

The priority at which the path will be captured.

processLinks boolean

The boolean specifying whether the links present in the capture will be processed.

captureExpiredPages boolean

The boolean specifying whether the links corresponding to expired pages will be recaptured.

captureNewPages string

The boolean specifying whether the links corresponding to unknown pages will be recaptured.

List pending captures

Arguments

site-token required

The token of the website.

limit optional default to 10

The limit on the number of objects to be returned. Limit can range between 1 and 100 items.

page optional default to 1

The page number to be retrieved.

orderBy optional default to "path"

The name of the field on which the results will be ordered. Could be "path", "date" or "priority".

from optional

The date from which pending capture objects will be returned.

to optional

The date to which pending capture objects will be returned.

priority optional

The value of the priority on which the results will be filtered.

desc optional default to false

The sort direction: ascending (default) or descending when true.

state optional

The state of the pending captures you want to list. By default, all states will be listed. Could be "pending" or "processing".

Returns

The array of pending capture objects.

Delete site pending captures

Arguments

site-token required

The token of the website.

Body

A JSON array of paths to delete. The number of paths in the array must be less than or equal to 100.

Add or update pending captures

Add or update a list of site pending captures

Arguments

site-token required

The token of the website.

Body

A JSON array of string paths to be added/updated or a JSON object containing the following keys.

paths required

The array of paths to be be added or updated (limited to 100 paths).

priority optional, default to 3

The priority at which the paths will be captured. If not set, this property will not be modified for updated paths.

processLinks optional, default to site settings value

The boolean specifying whether the links present in a page must be automatically captured or not. If not set, this property will not be modified for updated paths.

captureExpiredPages optional, default to site settings value

The boolean specifying whether the links present in a page must be automatically recaptured if the current captures are expired. If not set, this property will not be modified for updated paths.

captureNewPages optional, default to site settings value

The boolean specifying whether the links present in a page must be automatically captured when there were never captured before. If not set, this property will not be modified for updated paths.

Capture logs

Capture log object

Attributes

path string

The path of the capture which generated the logs.

date ISO 8601 formated date

The date at which the capture was done.

List capture logs

Arguments

site-token required

The token of the website.

limit optional default to 10

The limit on the number of objects to be returned. Limit can range between 1 and 100 items.

startAfter optional

The URL encoded path after which logs should be listed.

Returns

The array of capture log objects.

Delete capture logs

Arguments

site-token required

The token of the website.

Body

A JSON array of paths to delete. The number of paths in the array must be less than or equal to 100.

Retrieve a capture log

Arguments

site-token required

The token of the website.

path required

The URL encoded path for which you want to retrieve the log.

Site crawler state

Retrieve the state of the crawler

Returns the status of the crawler, i.e. whether it is active or not.

Arguments

site-token required

The token of the website.

Returns

The object with a key named "active". The value for this key is a boolean. If true, the crawler is active.

Update the state of the crawler

Arguments

site-token required

The token of the website.

Body

A JSON object containing the following keys.

active optional

The boolean indicating if the crawler must be active or no. If not set, the state of the crawler stay unchanged.

sitemaps optional

The boolean indicating if the sitemaps should be added to the pending captures.

entryPoints optional

The boolean indicating if the entryPoints should be added to the pending captures.