REST API v4.0 Active (Production)
Visperity Developer REST API v4
In addition to the complete data management available through the control panel, the Visperity REST API allows you to automate URL indexing of new content directly from your CMS or eCommerce platform and remotely manage and query AI tools on-demand.
Core API Capabilities
Automated Vector Indexing
Multi-Language Search & Autocomplete
Real-Time AI Assistant Reasoning
Standardized JSON & HTTPS REST
Quick Query Example HTTPS GET
curl -X GET "https://api.visperity.com/v4/assistant?uid=YOUR_ACCOUNT_ID&apikey=YOUR_DATASET_KEY&search=shipping+rates&lang=en" \
-H "Referer: https://yourdomain.com" \
-H "Accept: application/json"All public search calls require both your
uid (Account ID) and apikey (Dataset Key) with domain whitelist verification.API Host & Authentication Protocol
All API requests must be made over secure HTTPS to https://api.visperity.com/v4.
🌐 Public Search & Assistant Queries
Authenticate via your Account ID (uid) and Dataset Key (apikey) query parameters, along with a validated HTTP Referer or Origin header matching your domain whitelist.
GET /v4/assistant?uid=YOUR_ACCOUNT_ID&apikey=YOUR_DATASET_KEY&search=...
🔑 Dataset Management CRUD Operations
Supply your master Account ID in the custom accountid header with every dataset or record management request.
accountid: YOUR_ACCOUNT_ID
Interactive Reference
Core API Endpoints
Click on any endpoint below to inspect required parameters, example request syntax, and JSON response models.
1. Public AI Assistant & Search APIs
GET /v4/assistant — AI Virtual Assistant query & answer generation ▾
Generates an intelligent contextual AI answer summary and relevant top resource links using vector similarity search.
| Parameter | Type | Description |
|---|---|---|
| uid Required | string |
Your Visperity Account ID. |
| apikey Required | string |
Your dataset API key. |
| search Required | string |
Customer question or search keywords (e.g. pricing plans). Also accepts search_query. |
| lang Optional | string |
Two-letter language code (e.g. en, es, fr). Defaults to en. |
| cid Optional | string |
Client conversation tracking session ID. |
| more_help Optional | integer |
Set to 1 to trigger in-depth secondary follow-up AI reasoning. |
Example cURL Request:
curl -X GET "https://api.visperity.com/v4/assistant?uid=YOUR_ACCOUNT_ID&apikey=YOUR_DATASET_KEY&search=How+do+I+cancel+my+subscription%3F&lang=en" \ -H "Referer: https://yourdomain.com" \ -H "Accept: application/json"
GET /v4/livesearch — Instant search autocomplete & predictions ▾
Executes rapid predictive semantic search across indexed dataset records to power live typeahead dropdowns.
| Parameter | Type | Description |
|---|---|---|
| uid Required | string |
Your Visperity Account ID. |
| apikey Required | string |
Your dataset API key. |
| search Required | string |
Input search query string. Also accepts q or search_query. |
| lang Optional | string |
Language locale code (e.g. en, es). |
Example cURL Request:
curl -X GET "https://api.visperity.com/v4/livesearch?uid=YOUR_ACCOUNT_ID&apikey=YOUR_DATASET_KEY&search=wireless+headphones" \ -H "Referer: https://yourdomain.com" \ -H "Accept: application/json"
GET /v4/embed — In-page embedded search results ▾
Fetches paginated semantic results formatted for inline website search page widgets.
| Parameter | Type | Description |
|---|---|---|
| uid Required | string |
Your Visperity Account ID. |
| apikey Required | string |
Your dataset API key. |
| search Required | string |
Search query or keyword. Also accepts keyword or search_query. |
| page Optional | integer |
Page number for pagination. Defaults to 1. |
Example cURL Request:
curl -X GET "https://api.visperity.com/v4/embed?uid=YOUR_ACCOUNT_ID&apikey=YOUR_DATASET_KEY&search=refund+policy" \ -H "Referer: https://yourdomain.com" \ -H "Accept: application/json"
2. Dataset & Content Management CRUD API
GET /v4/datasets — List all configured datasets in your account ▾
Lists all Visperity AI Datasets associated with your account, returning the unique Dataset API Key, dataset name, and count of indexed URLs.
Example cURL Request:
curl -X GET "https://api.visperity.com/v4/datasets" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Accept: application/json"
Example Response (200 OK):
[ { "api-key": "9F9858D16C1B558ADEBDB0077EBF14E419-3834157", "dataset-name": "My Website", "dataset-urls": "13" }, { "api-key": "C8D063E8A17CC9A0A3262F9AB601EFEF19-3454004", "dataset-name": "My Online Store", "dataset-urls": "376" } ]
POST /v4/datasets — Create a new dataset in your account ▾
Creates a new Dataset in your account with the name you set in the dataset-name field.
| Field | Type | Description |
|---|---|---|
| dataset-name Required | string |
Descriptive name for your new dataset. (Also accepts dataset_name). |
Example cURL Request:
curl -X POST "https://api.visperity.com/v4/datasets" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Content-Type: application/json" \ -d '{ "dataset-name": "New Online Store Dataset" }'
Example Response (201 Created):
[ { "api-key": "BA19F91CE80C99A599B06D5BE1B7DB0A-5290938", "dataset-name": "New Online Store Dataset" } ]
GET /v4/datasets/{dataset-api-key} — Retrieve all URL content resource records for a dataset ▾
Retrieves all current URL resource records for the specified dataset. Returns the URL of the resource along with the unique record ID (ai-record-id) used for updating, viewing, or deleting.
| Path Variable | Type | Description |
|---|---|---|
| dataset-api-key Required | string |
The unique API key string of the dataset. |
Example cURL Request:
curl -X GET "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Accept: application/json"
Example Response (200 OK):
[ { "resource-url": "https://visperity.com/ai-live-site-search/", "ai-record-id": "4379A4F7A6155E48A53FA9ACB008FA33253-9553838" }, { "resource-url": "https://visperity.com/ai-powered-site-search-results/", "ai-record-id": "16EC810515AEF7FA42A14C0087D4A71F253-7006466" }, { "resource-url": "https://visperity.com/ai-site-assistant/", "ai-record-id": "E06D98C0C39F8122EF646E369F4AD3B5253-3158132" } ]
POST /v4/datasets/{dataset-api-key} — Add URL to dataset with automatic web scraper indexing ▾
Posts a new URL into your dataset and indexes the content of the page automatically using the automated web scraper.
| Field | Type | Description |
|---|---|---|
| resource_url Required | string |
The destination URL of the web page or resource. |
| price Optional NEW in v4 | string |
Product or service price to display in search cards (e.g. 29.99, $49.00). |
| language_code Optional NEW in v4 | string |
Target language locale code (e.g. en, es, fr, de). Defaults to en. (Also accepts lang). |
| product_skus Optional | string |
Product SKU(s) associated with the item for exact SKU match lookups. Separate multiple SKUs with commas. |
Example cURL Request:
curl -X POST "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Content-Type: application/json" \ -d '{ "resource_url": "https://visperity.com/pricing", "price": "29.00", "language_code": "en", "product_skus": "VISP-PLAN-01, VISP-PRO" }'
Example Response (201 Created):
[ { "ai-record-id": "8BBDAF25DCD963F521DAC093DE6F8C33227-1600290", "resource-title": "Visperity AI - Transparent Pricing & Plans" } ]
POST /v4/datasets/{dataset-api-key} — Add URL to dataset with manually defined content & metadata ▾
Posts a new URL into your dataset with explicit content provided in the request payload instead of scraping automatically. Automatically replaces any existing records sharing the identical URL.
| Field | Type | Description |
|---|---|---|
| resource_url Required | string |
Destination URL linked from search results and virtual assistant dialogue cards. |
| title Required | string |
Title of the resource, article, or product. |
| content Required | string |
The full text content to be vectorized and embedded. |
| price Optional NEW in v4 | string |
Product or service price to display in search cards (e.g. 99.00, $149.99). |
| language_code Optional NEW in v4 | string |
Language locale code (e.g. en, es, fr, de). Defaults to en. (Also accepts lang). |
| search_excerpt Optional | string |
Custom summary excerpt for embedded search. If omitted, an AI summary is auto-generated. |
| exclude_indexing Optional | string |
Yes or No (Default: No). Protects manual content from automatic crawler overwrites. |
| product_skus Optional | string |
SKU codes for exact product lookups. Comma-separated. |
| featured_image Optional | string |
Full image URL for display in embedded and live search result cards. |
| external_id Optional | string |
Unique database record ID from your third-party CMS or eCommerce platform for synchronized PATCH updates. |
Example cURL Request:
curl -X POST "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Content-Type: application/json" \ -d '{ "resource_url": "https://example.com/products/wireless-headphones", "title": "UltraBass Wireless Headphones", "content": "Premium noise-canceling over-ear wireless headphones with 40-hour battery life and fast charging.", "price": "99.00", "language_code": "en", "search_excerpt": "High-fidelity noise canceling headphones with 40h playtime.", "exclude_indexing": "Yes", "product_skus": "UB-WLS-001", "featured_image": "https://example.com/images/headphones.jpg", "external_id": "PROD-99882" }'
Example Response (201 Created):
[ { "ai-record-id": "9F2F0794166D2B4D42C9D85567A9D495260-4410138", "resource-title": "UltraBass Wireless Headphones" } ]
GET /v4/datasets/{dataset-api-key}/{ai-record-id} — Retrieve full details of a specific content record ▾
Views the complete indexed details of an individual URL content resource record.
| Path Variable | Type | Description |
|---|---|---|
| dataset-api-key Required | string |
The dataset API key. |
| ai-record-id Required | string |
Unique AI record identifier string. |
Example cURL Request:
curl -X GET "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY/4379A4F7A6155E48A53FA9ACB008FA33253-9553838" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Accept: application/json"
Example Response (200 OK):
[ { "ai-record-id": "4379A4F7A6155E48A53FA9ACB008FA33253-9553838", "resource_url": "https://visperity.com/ai-live-site-search/", "title": "AI Live Site Search", "content": "Visperity AI Powered Live Search super-charges your search form with real-time drop-down results...", "search_excerpt": "Visperity AI Live Search provides real-time, AI-optimized predictive search dropdowns.", "exclude_indexing": "No", "product_skus": "live search, sb-pro", "price": "99.00", "language_code": "en", "featured_image": "https://d3fpiavoj5h8pj.cloudfront.net/7413-3668-594631.jpg", "date_added": "2023-10-01 13:51:14", "date_updated": "2023-12-14 14:37:33" } ]
PUT /v4/datasets/{dataset-api-key}/{ai-record-id} — Update content record details by AI Record ID ▾
Updates an existing content resource record and recalculates vector embeddings. Note: The original destination URL is immutable and cannot be altered.
| Field | Type | Description |
|---|---|---|
| title Required | string |
Updated title of the resource. |
| content Required | string |
Updated text body to re-index into vector embeddings. |
| price Optional NEW in v4 | string |
Updated product/service price value. |
| language_code Optional NEW in v4 | string |
Updated language locale code (e.g. en, es). (Also accepts lang). |
| search_excerpt Optional | string |
Updated search excerpt. |
| exclude_indexing Optional | string |
Yes or No. |
| product_skus Optional | string |
Updated SKU numbers. |
| featured_image Optional | string |
Updated thumbnail image URL. |
Example cURL Request:
curl -X PUT "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY/16EC810515AEF7FA42A14C0087D4A71F253-7006466" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Content-Type: application/json" \ -d '{ "title": "Updated ABC Widget", "content": "The ABC product is designed to complement existing installations with no tools required.", "price": "89.00", "language_code": "en", "search_excerpt": "Complete installation guide and product specs for ABC Widget.", "exclude_indexing": "Yes", "product_skus": "ABC-PRO-V2", "featured_image": "https://example.com/abc-updated.png" }'
Example Response (200 OK):
[ { "ai-record-id": "16EC810515AEF7FA42A14C0087D4A71F253-7006466", "resource-title": "Updated ABC Widget" } ]
PATCH /v4/datasets/{dataset-api-key}/{external-id} — Update content record using external CMS / platform ID ▾
Updates an existing content resource record matched by your external CMS or eCommerce platform ID (external_id), keeping sync without needing to track internal AI record IDs.
| Field | Type | Description |
|---|---|---|
| resource_url Required | string |
Current URL of the content resource. |
| title Required | string |
Title of the resource or product. |
| content Required | string |
Full text content for vector indexing. |
| price Optional NEW in v4 | string |
Updated product or service price value. |
| language_code Optional NEW in v4 | string |
Updated language locale code (e.g. en, es). (Also accepts lang). |
| search_excerpt Optional | string |
Search results summary excerpt. |
| exclude_indexing Optional | string |
Yes or No. |
| product_skus Optional | string |
Item SKU numbers. |
| featured_image Optional | string |
Featured product image URL. |
Example cURL Request:
curl -X PATCH "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY/EXT-PROD-99882" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Content-Type: application/json" \ -d '{ "resource_url": "https://example.com/products/wireless-headphones", "title": "UltraBass Wireless Headphones (Gen 2)", "content": "Now updated with active noise cancelation v2 and Bluetooth 5.3 support.", "price": "119.00", "language_code": "en", "search_excerpt": "Gen 2 wireless headphones with upgraded ANC.", "exclude_indexing": "Yes", "product_skus": "UB-WLS-002", "featured_image": "https://example.com/images/headphones-v2.jpg" }'
Example Response (200 OK):
[ { "ai-record-id": "16EC810515AEF7FA42A14C0087D4A71F253-7006466", "resource-title": "UltraBass Wireless Headphones (Gen 2)" } ]
DELETE /v4/datasets/{dataset-api-key}/{ai-record-id} — Remove record and purge vector embeddings ▾
Permanently removes an indexed content record and purges all cached vector embeddings from the search engine index.
| Path Variable | Type | Description |
|---|---|---|
| dataset-api-key Required | string |
The dataset API key. |
| ai-record-id Required | string |
Unique AI record identifier string to delete. |
Example cURL Request:
curl -X DELETE "https://api.visperity.com/v4/datasets/YOUR_DATASET_KEY/C7BC029E552E5721414D7C71944349D7240-9630369" \ -H "accountid: YOUR_ACCOUNT_ID" \ -H "Accept: application/json"
Example Response (200 OK):
[ { "ai-record-id": "C7BC029E552E5721414D7C71944349D7240-9630369", "status": "Record Deleted" } ]
Postman Workspace
Open in Postman → Official Postman Collection
Download pre-configured test collections, inspect complete JSON response schemas, and run mock requests instantly.
Start Building with Visperity API Today
Manage your API keys, monitor session usage quotas, and customize widget designs from your dashboard.