Shop Bot Pro REST API v3

## Sections
• [Getting Started](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/getting-started.md): All Shop Bot Pro REST API requests require your API ACCOUNT ID value in the request header. Replace the {{your-account-id'}} placeholder in the accountid field with the value that is shown in your Shop Bot Pro control panel under 'My Account'.
• [List Account Datasets](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/list-account-datasets.md): Lists all of your Shop Bot Pro Datasets. Successful GET request returns Status code 200 and JSON in following format: [ {"api-key": "567SC6D5461651A5219-53597","dataset-name": "Default Dataset","dataset-urls": "1"}] "api-key": is the unique ID used to retreive the URLs for the dataset or add new URLs to the dataset. "dataset-name": is the descriptive name for the dataset. "dataset-urls ": # of URLs indexed (added) in the specifed dataset
• [Add New Dataset](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/add-new-dataset.md): Creates new Dataset in your account with the name you set in the dataset-name field. Successful POST request returns status code 201 and JSON in following format: [ {"api-key": "567SC6D5461651A5219-53597","dataset-name": "Default Dataset"}] "api-key": is the unique ID used to retreive the URLs for the dataset or add new URLs to the dataset. "dataset-name": descriptive name for the new dataset.
  • [Retrieve Url Content Resources](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/add-new-dataset/retrieve-url-content-resources.md): This request retreives all the current URL resource records for the specified dataset. This request requires the api-key of the dataset. The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. This resource api call will return all the results of the specified dataset in the following JSON respnse format with the URL of the resource along with the unique record ID (ai-record-id) which can be used for updating, deleting and viewing the specific resource using the correponding api request types. [ {"resource-url": " https://shopbotpro.com/ai-live-site-search/" ,"ai-record-id": "4379A4F7A6155E48A53FA9ACB008FA33253-9553838"},{"resource-url": " https://shopbotpro.com/ai-powered-site-search-results/" ,"ai-record-id": "16EC810515AEF7FA42A14C0087D4A71F253-7006466"}] Note: All records for the dataset will be returned . Therefore, large datasets that contain thousands of records, may take severall seconds to process and return the large list of records in the JSON response. We have tested the response with live datasets containing up to 350,000 records without time-out or client data download issues. If the dataset is empty (does not contain any resource URL records), the following JSON message will be returned along with a 404 response code: {{"api-error": "NO RECORDS FOUND: There are no URL resource records inside the dataset with api-key: XXXXX-XXXXX-XXXX"}}
• [Add Url To Dataset (auto Index)](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/add-url-to-dataset-auto-index.md): POSTs a new URL into your dataset and index the content of the page automatically using our web scraper. This API call requires two parameters: The api-key of the dataset in the endpoint and the URL of the resource that you want to add from your website or online in the body. The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. If you want to POST a new URL into your dataset with manually defined content instead of automatic indexing, use the ADD URL TO DATASET (MANUAL INDEX) api call instead. If you are adding content from your external CMS or ecommerce system, you should use the ADD URL TO DATASET (MANUAL) POST. The following required and optional body (form field) values: resource_url : REQUIRED: The url that the resource will link to from search results lists and virtual assistant dialogs. product_skus : OPTIONAL : The Product SKU or SKU numbers that are associated with an item. This an optional field for onlline stores that want to provide exact SKU searches for items if they are not published on the page. Seperate each SKU by a comma. The URL will be indexed and a status code of 201 plus the indexed record ID will be returned in the following example JSON format. [{"ai-record-id" : "1508E296D1F18C70C0F02537704C9A5B227-19883753291","resource-title" : "Meta Title Of Page"}] If any of the following errors are encountered, a status code of 400 Bad Request will be returned : The api-key for the dataset is invalidThe URL provided is invalid or unreachable. If there is an error with the POST, the json response will be in the following example format: [{"api-error": "Invalid API key. Please check that the dataset api-key in the endpoint url exists."}]
• [Add Url To Dataset (manual)](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/add-url-to-dataset-manual.md): POSTs a new URL into your dataset with content provided in the api post instead of scraping the content of the page URL and indexing it automatically. IMPORTANT: To allow admins to replace automatically indexed URLs with manually added URLs without having to delete them one-by-one first, the MANUAL dataset URL post will automatically delete any records in the dataset with the exact same URL prior to posting the new manually specified content. If you are adding resources directly from your CMS or eCommerce platform, it is recommended to include the unique ID value from your external system in the external_id field. Therefore you can update it in the future using the UPDATE Resource Record By External ID. The MANUAL DATASET RESOURCE URL RECORD API POST requires: The api-key of the dataset in the endpoint: The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. And the following required and optional body (form field) values: resource_url : REQUIRED: The url that the resource will link to from search results lists and virtual assistant dialogs. title : REQUIRED: The title of the resource, page or product name. content : REQUIRED: The text content that you want indexed for the resource. search_excerpt: OPTIONAL: The search results summary. This field is only displayed in the embedded search results and not used in the live search or virtual assitant tools. If the search_excerpt content is excluded, an Ai generated excerpt will be added to the record instead. exclude_indexing : YES/NO . Exclude this Record From Automatic Content Re-Indexing. Default is NO. Recommend keeping this value turned ON (YES) for manually entered URL resources. If turned OFF (value=No), your manually entered content will be replaced the next time the page is auto-scanned (indexed). product_skus : OPTIONAL : The Product SKU or SKU numbers that are associated with an item. This an optional field for onlline stores that want to provide exact SKU searches for items if they are not published on the page. Seperate each SKU by a comma. featured_image : OPTIONAL : Include the URL of an optional image to appear in the embedded search results display. This feature is only valid for embedded search results and does not appear on the live search or the virtual assistant tools. external_id : OPTIONAL : The unique database record ID value from your third party CMS or ecommerce platform that identifies this record. Recommend using this feature to allow auto-updating of this resource when you make changes in your external platform. Upon a successul post, the submitted content will be indexed and a status code of 201 will be returned plus the indexed record ID will be returned in the JSON format: [{"ai-record-id" : "1508E296D1F18C70C0F02537704C9A5B227-19883753291","resource-title" : "Meta Title Of Page"}] If any of the following errors are encountered, a status code of 400 Bad Request will be returned. The api-key for the dataset is invalid The URL provided is invalid or unreachable. The title field is empty. The content field is empty. If there is an error with the POST, the json response will be in the example format: [{"api-error": "Invalid API key. Please check that the dataset api-key in the endpoint url exists."}]
• [Get Url Resource Record Details](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/get-url-resource-record-details.md): This request views the details of a URL resource (content record) from the specified dataset. This request requires the api-key of the dataset and the api-record-id value in the endpoint. The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. The api-record-id is a individual resource URl record in the dataset. You can retrieve all the api-record-id values for a specific dataset using the RETRIEVE URL CONTENT RESOURCES api call or inside your control panel when viewing a resource record. The following field data is returned in JSON format (REQUIRED or OPTIONAL is for informational purposes for iwhen you want to update the record) ai-record-id: The unique record ID for this resource. (This is the same value that is sent in with the api URL endpoint.) resource_url : Read-only: The url that the resource will link to from search results lists and virtual assistant dialogs. (This field cannot be updated after the record is added) title: REQUIRED: The title of the resource, page or product name. content : OPTIONAL: The text content that was used for the AI indexing. search_excerpt: OPTIONAL: The search results summary. This field is only displayed in the embedded search results and not used in the live search or virtual assitant tools. If the search_excerpt content is excluded, an Ai generated excerpt will be added to the record instead. exclude_indexing : REQUIRED - YES/NO . Exclude this Record From Automatic Content Re-Indexing. Default is NO. Recommend keeping this value turned ON (YES) for manually entered URL resources. If turned OFF (value=No), your manually entered content will be replaced the next time the page is auto-scanned (indexed). product_skus : OPTIONAL : The Product SKU or SKU numbers that are associated with an item. This an optional field for onlline stores that want to provide exact SKU searches for items if they are not published on the page. Seperate each SKU by a comma. featured_image : OPTIONAL : Include the URL of an optional image to appear in the embedded search results display. This feature is only valid for embedded search results and does not apper on the live search or the virtual assistant tools. date_added : Read-only field for the original record creation date. date_updated: Read-only field with the date this record was last modified either through the API, through the control panel or via an automatic reindexing.
• [Update Url Content Record Json](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/update-url-content-record-json.md): Updates an existing content resource URL record. The UPDATE URL Content Record JSON PUT command requires: The api-key of the dataset and the api-record-id value in the endpoint. The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. The api-record-id is a individual resource URl record in the dataset. You can retrieve all the api-record-id values for a specific dataset using the RETRIEVE URL CONTENT RESOURCES api call or inside your control panel when viewing a resource record. Unlike the ADD URL TO DATASET (MANUAL) api call which can also be used to "update" a URL resource by replacing the existing URL record with a new record, this API call simply updates the existing record with the following fields that are sent in the body of the message in "raw" JSON format. title : REQUIRED: The title of the resource, page or product name. content : REQUIRED: The text content that you want indexed for the resource. exclude_indexing : YES/NO . Exclude this Record From Automatic Content Re-Indexing. Default is NO. Recommend keeping this value turned ON (YES) when updating from your external system. If turned OFF (value=No), your manually entered content will be replaced the next time the page is auto-scanned (indexed). product_skus : OPTIONAL : The Product SKU or SKU numbers that are associated with an item. This an optional field for onlline stores that want to provide exact SKU searches for items if they are not published on the page. Seperate each SKU by a comma. featured_image : OPTIONAL : Include the URL of an optional image to appear in the embedded search results display. This feature is only valid for embedded search results and does not apper on the live search or the virtual assistant tools. Note: you cannot update the record's URL value. If you need to modify the URL field, delete the record with the invalid or outdated URL and then post a new record with the correct or current URL for the resource. Example JSON body content: { "title": "ABC WIDGET","content": "The ABC PRODUCT is designed to compliment the DEF product. It can be installed along with XYZ units and it does not require any tools for installation. The ABC product was released in June 2021 and design by John Smith. The ABC product comes in black, white, blue and brown. It measures 12 inches wide x 8 inches in height and a depth of 4 inches. Made In USA.","search_excerpt": "","exclude_indexing": "Yes","product_skus": "ABC","featured_image": " https://db8x97cvhxeb1.cloudfront.net/abc-product.png" } Upon a successul post, the submitted content will be indexed and a status code of 200 will be returned plus the indexed record ID and revised record name (resource-title) will be returned in the JSON format: [{"ai-record-id" : "1508E296D1F18C70C0F02537704C9A5B227-19883753291","resource-title" : "Title Of Page"}] If any of the following errors are encountered, a status code of 400 Bad Request will be returned. The api-key for the dataset is invalid The api-record-id provided is not valid (no record found) The title field is empty. The content field is empty. If there is an error with the PUT COMMAND the json response will be in the example format: [{"api-error": "Invalid API key. Please check that the dataset api-key in the endpoint url exists."}]
• [Update Resource Record By External Id](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/update-resource-record-by-external-id.md): Updates an existing content resource URL record. The UPDATE Resource Record by External ID command requires: The api-key of the dataset and the api-record-id value in the endpoint. The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. The external-id record value from your external ecommerce or CMS platform. This value is sent in during the Add URL TO DATASET (MANUAL) or you can update an existing record in the control panel with this value. The following fields can be patched (updated): resource_url : REQUIRED : The URL of the content resource. title : REQUIRED: The title of the resource, page or product name. content : REQUIRED: The text content that you want indexed for the resource. search_excerpt: OPTIONAL: The search results summary. This field is only displayed in the embedded search results and not used in the live search or virtual assitant tools. If the search_excerpt content is excluded, an Ai generated excerpt will be added to the record instead. exclude_indexing : YES/NO . Exclude this Record From Automatic Content Re-Indexing. Default is NO. Recommend keeping this value turned ON (YES) when updating from your external system. If turned OFF (value=No), your manually entered content will be replaced the next time the page is auto-scanned (indexed). product_skus : OPTIONAL : The Product SKU or SKU numbers that are associated with an item. This an optional field for onlline stores that want to provide exact SKU searches for items if they are not published on the page. Seperate each SKU by a comma. featured_image : OPTIONAL : Include the URL of an optional image to appear in the embedded search results display. This feature is only valid for embedded search results and does not apper on the live search or the virtual assistant tools. Example JSON body content: { "resource_url":" https://shopbotpro.com/abc-widget/" ,"title": "ABC WIDGET","content": "The ABC PRODUCT is designed to compliment the DEF product. It can be installed along with XYZ units and it does not require any tools for installation. The ABC product was released in June 2021 and design by John Smith. The ABC product comes in black, white, blue and brown. It measures 12 inches wide x 8 inches in height and a depth of 4 inches. Made In USA.","search_excerpt": "","exclude_indexing": "Yes","product_skus": "ABC","featured_image": " https://db8x97cvhxeb1.cloudfront.net/abc-product.png" } Upon a successul post, the submitted content will be indexed and a status code of 200 will be returned plus the indexed record ID and revised record name (resource-title) will be returned in the JSON format: [{"ai-record-id" : "1508E296D1F18C70C0F02537704C9A5B227-19883753291","resource-title" : "Title Of Page"}] If any of the following errors are encountered, a status code of 400 Bad Request will be returned. The api-key for the dataset is invalid The external-id provided is not valid (no record found) The title field is empty. The content field is empty. If there is an error with the PATCH COMMAND the json response will be in the example format: [{"api-error": "Invalid API key. Please check that the dataset api-key in the endpoint url exists."}]
• [Delete Url Resource (content) Record](https://app.theneo.io/shopbotpro/shop-bot-pro-rest-api-v3/delete-url-resource-content-record.md): This request removes a URL resource (content record) from the specified dataset. This request requires the api-key of the dataset and the api-record-id value in the endpoint. The api-key is specific to the dataset and can be retreived using the LIST ACCOUNT DATASETS api call or inside your control-panel under the datasets area. The api-record-id is a individual resource URl record in the dataset. You can retrieve all the api-record-id values for a specific dataset using the RETRIEVE URL CONTENT RESOURCES api call or inside your control panel when viewing a resource record. WARNING: Do not test this feature using any URL resource record that you want to retain. The record will be automatically deleted from the system if it is specified as the ai-record-value and there is no option to confirm the request and it cannot be reversed. To test this function, create a test (dummy) URL resource record and use that record as your test delete API call value (ai-record-id).