REST API
The SearchBlox REST API provides programmatic access to manage search collections and documents through standard HTTP methods. This interface supports JSON payloads for seamless integration with custom applications and workflows.
Supported Collection Types
- Custom Collections (Full CRUD operations)
- WEB Collections (Document-level operations)
- File Collections (Document-level operations)
SearchBlox REST-API provides methods for working with standard and custom collections by means of REST requests with JSON payloads. Index, delete, clear and check the status of custom collections, or create new custom collections using REST-API. Individual documents can also be added or deleted in WEB and file collections.
SearchBlox Development Environment
API Explorer (Built-in Tool)
The SearchBlox API Explorer is an integrated development environment that provides:
- Interactive documentation for all REST API endpoints
- Live testing capabilities
- Automatic JSON payload generation
- Built-in authentication handling
Access Instructions - Navigate to:
https://<your-searchblox-server>:8443/api
(Default:https://localhost:8443/api
) - Authenticate using your SearchBlox admin credentials
Postman
POSTMAN is another external third-party tool that can be used with Searchblox JSON API. The settings for POSTMAN API can be found at the end of this documentation. For more details on the POSTMAN API tool, refer to https://www.getpostman.com.
Base URL: https://:8443/api/rest
Authentication:
Type: Basic Auth
Username: Your SearchBlox admin username
Password: Your SearchBlox admin password
Headers:
Content-Type: application/json
Accept: application/json
Index
Index URL
REST-JSON API
https://localhost:8443/rest/v2/api/add
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "5BD07C1F3E8555C66E1E5B10FCAB315F",
"document" : {
"colname" : "Custom",
"url" : "http://www.searchblox.com",
"uid" : "http://www.searchblox.com",
"location":"http://www.searchblox.com",
"alpha" : "string",
"size" : "44244",
"title" : "Text",
"keywords" : "keywords",
"description" : "SearchBlox Content Search Software",
"content" : "content",
"lastmodified" : "14 January 2021 06:19:42 GMT",
"contenttype" : "HTML",
"urllen": "300",
"meta":{
"location":"San Francisco",
"temp":"23",
"weather":"sunny"
}
}
}
Document Description
API Request Parameters
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 5BD07C1F3E8555C66E1E5B10FCAB315F |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | Custom |
url | URL of the document. | String | http://www.searchblox.com |
uid | Unique identifier for the document (could be a URL or ID). | String | http://www.searchblox.com |
location | Location related to the document. | String | http://www.searchblox.com |
alpha | Custom string or identifier related to the document. | String | string |
size | Size of the document (in bytes). | Integer | 44244 |
title | Title of the document. | String | Text |
keywords | Keywords associated with the document. | String | keywords |
description | Description of the document. | String | SearchBlox Content Search Software |
content | Content of the document. | String | content |
lastmodified | Last modified date of the document. | String | 14 January 2021 06:19:42 GMT |
contenttype | Content type of the document. | String | HTML |
urllen | URL length (typically used for tracking or limiting). | Integer | 300 |
meta | Object containing metadata about the document. | Object | N/A |
location | Location related to the metadata (e.g., physical location). | String | San Francisco |
temp | Temperature information related to the document location. | Integer | 23 |
weather | Weather condition related to the document location. | String | sunny |
Response Codes
JSON
code | Description |
---|---|
100 | Document indexed successfully |
101 | Document indexing failed |
501 | Collection not found |
502 | Invalid Document URL/Location |
Update Meta Data
updatemetadata URL
REST-JSON API
https://localhost:8443/rest/v2/api/updatemetadata
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "31372006F71D0A874BBE0F02894C7E0A",
"document" : {
"colname" : "custom",
"url" : "http://www.searchblox.com",
"meta":{
"location":"San Francisco",
"temp":"23",
"weather":"sunny"
}
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 31372006F71D0A874BBE0F02894C7E0A |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | custom |
url | URL of the document. | String | http://www.searchblox.com |
meta | Object containing metadata about the document. | Object | N/A |
location | Location related to the metadata (e.g., physical location). | String | San Francisco |
temp | Temperature information related to the document location. | Integer | 23 |
weather | Weather condition related to the document location. | String | sunny |
Response Codes
Code | Description |
---|---|
7000 | Meta Data updated successfully |
7001 | Meta Data update failed |
601 | API key is not found/invalid |
7003 | Document not found |
Delete
This is to delete documents only in a custom collection
Delete URL
REST-JSON API
https://localhost:8443/rest/v2/api/delete
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "302D02144F115712204DD54596EDDCCEDD284878D3BBFA130215008BF2501E38561A439C9260D7",
"document" :
{
"colname" : "Custom_Collection", "uid" : "http://www.searchblox.com"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 302D02144F115712204DD54596EDDCCEDD284878D3BBFA130215008BF2501E38561A439C9260D7 |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | Custom_Collection |
uid | Unique identifier for the document (could be a URL or ID). | String | http://www.searchblox.com |
Response Codes
JSON
2001 | Document Deleted Successfully |
2002 | Document requested for deletion does not exist. |
501 | Invalid Collection Name |
Document Status
Status URL
REST-JSON API
https://localhost:8443/rest/v2/api/status
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "302D02144F115712204DD508BF2501E38561A439C9260D509DBF12952619177", "document" :
{
"colname" : "Custom_Collection", "uid" : "http://www.searchblox.com"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 302D02144F115712204DD508BF2501E38561A439C9260D509DBF12952619177 |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | Custom_Collection |
uid | Unique identifier for the document (could be a URL or ID). | String | http://www.searchblox.com |
Response Codes
JSON
301 | Document not found |
Clear Collection
Clear URL
REST-JSON API
https://localhost:8443/rest/v2/api/clear
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "302D02144F115712204DD54596EDDCCEDD284878D3BBFA130215008BF2501E38561A439C9260D509DBF12952619177",
"document" :
{
"colname" : "Custom_Collection"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 302D02144F115712204DD54596EDDCCEDD284878D3BBFA130215008BF2501E38561A439C9260D509DBF12952619177 |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | Custom_Collection |
Response
JSON
400 | Collection has been cleared successfully |
501 | Collection not found |
Add collection
You can add a new custom collection through REST-API using JSON payload using the details provided here.
Add Collection URL
REST-JSON API
https://localhost:8443/rest/v2/api/coladd
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "DAB42B6BDDFDD1F079C12B2FFEDCB92E5",
"public": true,
"encrypt": false,
"document" :
{
"colname" : "custom",
"coltype":"custom",
"language" : "en"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | DAB42B6BDDFDD1F079C12B2FFEDCB92E5 |
public | Whether the document is public or private. | Boolean | true |
encrypt | Indicates whether encryption is enabled or not. | Boolean | false |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | custom |
coltype | Type of the collection (can be a predefined or custom type). | String | custom |
language | Language of the document. | String | en |
Response Codes
JSON
900 | Custom collection with name <colname> has been created |
400 | Failed creating custom collection |
Delete Collection
You can delete existing custom collections through REST-API using JSON payload using the details given here.
Delete Collection URL
REST-JSON API
https://localhost:8443/rest/v2/api/coldelete
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "5BD07C1F3E8555C66E1E5B10FCAB315F",
"document" :
{
"colname" : "Custom_Collection"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 5BD07C1F3E8555C66E1E5B10FCAB315F |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | Custom_Collection |
Response
JSON
800 | Custom collection with name <colname> has been deleted. |
501 | Collection does not exist |
Add/Update Document
You can add documents to an HTTP collection or File collection through REST-API using JSON payload using the details given here.
Add/update Document URL
REST-JSON API
https://localhost:8443/rest/v2/api/docadd
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "5BD07C1F3E8555C66E1E5B10FCAB315F", "document" :
{
"colname" : "CollectionName", "location" : "http://www.searchblox.com"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 5BD07C1F3E8555C66E1E5B10FCAB315F |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | CollectionName |
location | Location related to the document, could be a URL or path. | String | http://www.searchblox.com |
Response
JSON
1001 | Document has been added/updated successfully |
1002 | Document add/update failed |
501 | Collection not found |
Add/Update Synonyms
Add/Update-Synonyms URL
https://localhost:8443/rest/v2/api/update-synonyms
Method
POST
Media Type
application/json
Headers
content-type : application/json
accept: application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
Adding or Updating Synonyms
{
"apikey" : "42C9A0E016FAC44726FA7DE049C01E3A",
"colname": "Custom_Collection",
"synonyms": [
"10, ten",
"zip, zipcode"
]
}
Document Description
This table describes the parameters required for making API requests related to synonym mapping.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 42C9A0E016FAC44726FA7DE049C01E3A |
colname | Collection name where the synonyms will be applied. | String | Custom_Collection |
synonyms | List of synonym pairs that will be mapped. | Array | ["10, ten", "zip, zipcode"] |
Response
JSON
200 | Collection Synonyms saved successfully. |
601 | API key is not found/invalid |
Delete Document
You can delete documents from an HTTP collection or File collection through REST-API from the Delete Document tab in API, using the JSON code given in the following Document Syntax section.
Delete Document URL
REST-JSON API
https://localhost:8443/rest/v2/api/docdelete
Method
POST
Media Type
REST-JSON API
application/json
Headers
SB-PKEY
LmfxTTDSeYxHTntJMHuhwRrGVICMaVN/wl/zPuQ3LtQDNRMnng5GpKIkgt0q1rCC/h6wDA==
Document Syntax
REST-JSON API
{
"apikey" : "5BD07C1F3E8555C66E1E5B10FCAB315F", "document" :
{
"colname" : "CollectionName", "location" : "http://www.searchblox.com"
}
}
Document Description
This table describes the parameters required for making API requests.
Field | Description | Type | Example Value |
---|---|---|---|
apikey | The API key used for authentication. | String | 5BD07C1F3E8555C66E1E5B10FCAB315F |
document | Object containing the document details. | Object | N/A |
colname | Collection name where the document will be stored. | String | CollectionName |
location | Location related to the document (could be a URL or path). | String | http://www.searchblox.com |
Response
JSON
2001 | Document Deleted Successfully |
502 | Invalid Document Location |
501 | Collection not found |
Response Codes
Document Syntax
{
"statusCode": 100,
"message": "Document indexed successfully",
"success": true
}
API Response Parameters
This table describes the parameters returned in the API response.
Field | Description | Type | Example Value |
---|---|---|---|
statusCode | The status code of the request. | Integer | 100 |
message | A message providing additional details about the request status. | String | "Document indexed successfully" |
success | Whether the request was successful or not. | Boolean | true |
Status Code Description
100 | Document indexed successfully |
101 | Document indexing failed |
2001 | Document Deleted Successfully |
2002 | Document delete failed. |
301 | Document Not Found |
400 | Collection has been cleared successfully |
401 | Clearing collection failed |
501 | Collection not found |
501 | Invalid Request |
502 | Invalid Document Location |
503 | Specified collection is not a CUSTOM collection. |
506 | Invalid Document UID |
800 | Custom collection with name has been deleted. |
900 | Custom collection with name has been created |
1001 | Document Added Successfully |
1002 | Document Couldn't Be Reached |
2001 | Document Deleted Successfully |
2002 | Specified collection is not a custom collection. |
Settings in POSTMAN API
Postman API is a third-party tool that can be used with SearchBlox API. The prerequisite settings that are required to work with SearchBlox API are as follows:
- URL to be given for each API function as mentioned under each function in the preceding documentation.
- Method to be selected is POST for all functions.
- Header to be added is Content-Type, which has to be given as a header. The value for the header for JSON API is application/json. This could be also done by selecting the dropdown JSON as required.
- Header parameter to be added is SB-PKEY. Value can be found in the Admin Users List for Super Admin and Admin users.
The screenshots JSON API on settings and result are given here. Select raw to view the status code for JSON API.
##JSON API POSTMAN settings
Updated about 1 month ago