AddSearch’s REST API provides programmatic access to use and manipulate and query data in your search index. Current version of our API is v1. We’re expanding API’s functionalities based on your feedback, so feel free to contact us if any ideas arise.

Base URL

All API URLs start with the following base URL:
Access is always over HTTPS. All calls to HTTP return 405 Method Not Allowed

Content type

API endpoints consume and produce JSON:
Calls with JSON payload must include Content-Type header, which can be added in curl with the following switch:

curl -H 'Content-Type:application/json' https://api...


Authentication is done with HTTP Basic Auth. Your index’s SITEKEY is the username and your secret API key is the password. You’ll find your SITEKEY and secret API key from the Dashboard’s Installation page. HTTP authentication in curl is done with the user switch:

curl --user ‘sitekey:secret-api-key’ https://api...

Obs! The Search API does not require authentication.

Date Format

AddSearch API uses ISO-8601 standard as the date format. Example of an accepted timestamp is:
Read more about ISO-8601 from

Rate limits

By default rate limits are monitored over 15 minutes time period. Every API call returns rate limit information in the following headers

X-Rate-Limit-Limit: The limit for a given request

X-Rate-Limit-Remaining: Requests left for the current 15 minute window

X-Rate-Limit-Reset: The time when the current usage count resets (seconds since Unix epoch)

Example headers returned by an API call:

X-Rate-Limit-Limit: 100

X-Rate-Limit-Remaining: 97

X-Rate-Limit-Reset: 1422615270

API Endpoints

You can make queries to your AddSearch index with the Search endpoint
GET /search/{index public key}
Query parameters are

term: Search term (mandatory)
page: Page to return. Each page contains 10 hits (optional, default: 1)
jsonp: JavaScript function call wrapped around the response JSON (optional)
categories: Limit search to certain categories (domain or URL path). E.g. “” would return results only from, 1xnews would return results from “*” path (optional)

For example:
page: 1,
total_hits: 1,
hits: [
id: "54f5b92d4e4766f4bc0ce2b05f80f58d",
url: "",
title: "AddSearch REST API",
highlight: "AddSearch’s REST API provides programmatic access to your search index",
ts: "2015-01-22T11:56:10",
images: {
main: "",
capture: ""
score: 0.790107

Fields in the returned JSON are:

page: Page number passed as a query parameter
total_hits: Total number of documents matching the search term

Elements in the hits array:
id: Document’s ID (md5 of the URL)
url: Document’s URL
title: Documents’s title
highlight: Part of the document’s content
ts: Document’s publishing date. if unknown, the time when the document was initially indexed
images.main: URL of the main image (e.g. og:image). Null if missing
images.capture: URL of the screen capture. Null if missing
score: How well the search term matches the document

Obs! The search API does not require authentication.

Get document’s status

You can get the status of a document with the following request. Doc id is the MD5 hash of a full URL with protocol and possible query parameters. For example the doc id of is 3b1d053e2fdf65f178dc5d1b5bd00f75

GET /indices/{index public key}/documents/{doc id}
API call returns following information:
"indexPublicKey": "index public key",
"docId": "md5 of url",
"statusInfo": "Duplicate of another-doc-id",
"lastFetched": "2015-01-13T13:43:01.000Z",
"duplicateOf": {
"href": "{index public key}/documents/{doc id}"
"content": {
"href": "{index public key}/documents/{doc id}/content"

Get document’s contents

Following the link in the “content” property of document’s status response the indexed content of the document is returned.

GET /indices/{index public key}/documents/{doc id}/content

The response is of the following form:

"title": "An example page",
"h1": "The heading on an example page",
"h2": "",
"mainContent": "The indexed content on an example page",
"documentDate": "2015-02-10T14:11:13.000Z",
"language": "en",
"hiddenKeywords": null

The field “documentDate” is the ISO 8601 date that the document was created, if the information is available in the source document’s meta data, or if not, the date the document was initially indexed.

Hidden keywords is a space delimited list of manually defined keywords that when used as search keywords will match to this document, even  though they are not present in the documents indexed content.

Modify document’s hidden keywords

You can modify the hidden keywords of a document by POSTing the new value to this endpoint.

POST /indices/{index public key}/documents/{doc id}/content/hiddenKeywords


"hiddenKeywords": "list of space delimited hidden keywords"

The endpoint returns HTTP 200 OK if succesful.

Add a page to index or re-crawl an URL

You can add new pages to your index or re-crawl existing documents with following endpoint. Re-indexing is executed at the latest in a minute or two.

POST /crawler
"action": "FETCH",
"indexPublicKey": "SITEKEY",
"url": ""

Returns HTTP 202 ACCEPTED with payload e.g.

"message": "Scheduled",
"docId": "doc id"