API Documentation

Welcome to the Viesearch API. Our API allows developers to interact with our search index, fetch site statistics, and submit content programmatically.

The API is public and follows RESTful principles where applicable.

General Information

The base URL for all API requests is https://viesearch.com. All responses are returned in JSON format unless otherwise specified.

Authentication: All API endpoints require a valid API key. You can find or generate your unique API key in your Account Settings. Pass the key in the x-api-key HTTP header with every request.

For endpoints that support pagination, the results per page (limit) are fixed to match the standard Viesearch platform views to ensure consistency across all interfaces. Users can navigate through results using the p parameter.

Endpoints

GET /api/search

The primary search endpoint for the Viesearch index. Supports full-text search, category filtering, and multiple sorting strategies. Returns up to 25 results per page.

Parameter	Type	Description
q *	string	The search query string.
c	string	Optional category slug to filter results within a specific category and its descendants.
s	string	Sort strategy: r (most reciprocal), v (popular results), l (most liked), c (most commented), f (featured). Default: newest additions.
p	number	The page number to retrieve (default: 1).

curl -X GET "https://viesearch.com/api/search?q=curated+content" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/search?q=design", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.results));

import requests

url = "https://viesearch.com/api/search"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}
params = {"q": "design"}

response = requests.get(url, headers=headers, params=params)
print(response.json()["results"])

GET /api/urls/:token

Fetches the full details of a specific listing using its unique token identifier. Responses are cached for 60 seconds.

Parameter	Type	Description
token *	string	The unique alphanumeric token of the listing.

curl -X GET "https://viesearch.com/api/urls/abc123" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/urls/abc123", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.result));

import requests

url = "https://viesearch.com/api/urls/abc123"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["result"])

GET /api/categories

Returns a minimized list of all active categories. This is ideal for building search dropdowns or index navigation. Responses are cached for 24 hours.

curl -X GET "https://viesearch.com/api/categories" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/categories", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.results));

import requests

url = "https://viesearch.com/api/categories"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["results"])

GET /api/activity

Returns a paginated list of community activity, including editor registrations and community updates. Returns up to 25 items per page.

Parameter	Type	Description
p	number	The page number to retrieve (default: 1).

curl -X GET "https://viesearch.com/api/activity" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/activity", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.results));

import requests

url = "https://viesearch.com/api/activity"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["results"])

GET /api/newest

Returns the latest additions to the Viesearch index. Returns up to 25 results per page.

Parameter	Type	Description
p	number	The page number to retrieve (default: 1).
s	string	Sort strategy: r (recently reciprocal), l (recently liked), c (recently commented). Default: newest additions.

curl -X GET "https://viesearch.com/api/newest" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/newest", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.results));

import requests

url = "https://viesearch.com/api/newest"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["results"])

GET /api/popular

Returns the most engaged listings across the platform. Returns up to 25 results per page.

Parameter	Type	Description
p	number	The page number to retrieve (default: 1).
s	string	Sort strategy: r (most reciprocal), l (most liked), c (most commented). Default: popular results.

curl -X GET "https://viesearch.com/api/popular" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/popular", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.results));

import requests

url = "https://viesearch.com/api/popular"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["results"])

GET /api/featured

Returns the current set of featured listings. Returns up to 25 results per page.

Parameter	Type	Description
p	number	The page number to retrieve (default: 1).

curl -X GET "https://viesearch.com/api/featured" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/featured", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(data => console.log(data.results));

import requests

url = "https://viesearch.com/api/featured"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["results"])

GET /api/trending

Returns the top trending searches over the last 15 minutes, including trend direction (up, down, side) and hits. Returns up to 25 results per page.

Parameter	Type	Description
p	number	The page number to retrieve (default: 1).

curl -X GET "https://viesearch.com/api/trending" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/trending", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(trending => console.log(trending.results));

import requests

url = "https://viesearch.com/api/trending"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json()["results"])

GET /api/stats

Returns live database statistics, including total searches, submissions, indexed sites, and category counts.

curl -X GET "https://viesearch.com/api/stats" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/stats", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(stats => console.log(stats));

import requests

url = "https://viesearch.com/api/stats"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/suggestions

Returns search suggestions based on a query or trending keywords if no query is provided.

Parameter	Type	Description
q	string	The search term to get suggestions for.

curl -X GET "https://viesearch.com/api/suggestions?q=web" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE"

fetch("https://viesearch.com/api/suggestions?q=web", {
  headers: { "x-api-key": "vs_YOUR_API_KEY_HERE" }
})
.then(res => res.json())
.then(suggestions => console.log(suggestions.keywords));

import requests

url = "https://viesearch.com/api/suggestions"
headers = {"x-api-key": "vs_YOUR_API_KEY_HERE"}
params = {"q": "web"}

response = requests.get(url, headers=headers, params=params)
print(response.json()["keywords"])

POST /api/contact

Rate Limit: 1 request per 1 hour

Programmatically submit a support ticket or contact message. Requires a name, valid email, and message.

Parameter	Type	Description
name *	string	Sender full name.
email *	string	Sender valid email address.
message *	string	The message content.

curl -X POST "https://viesearch.com/api/contact" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com", "message": "API inquiry"}'

fetch("https://viesearch.com/api/contact", {
  method: "POST",
  headers: {
    "x-api-key": "vs_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Jane Doe",
    email: "jane@example.com",
    message: "API inquiry"
  })
})
.then(res => res.json())
.then(data => console.log(data));

import requests

url = "https://viesearch.com/api/contact"
headers = {
    "x-api-key": "vs_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "API inquiry"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

POST /api/submit

Rate Limit: 1 request per 30 seconds

Submit a new website resource to the Viesearch index. Submissions enter a manual review queue. If you are an agency submitting for a client, you may provide their email address. However, if the client is already a registered user, the submission will be rejected.

Parameter	Type	Description
url *	string	Website URL (including http/https).
email	string	Optional. Submitter email address. If omitted, defaults to the email associated with your API key.
category_slug	string	Target category slug (e.g., computers_and_technology).
title	string	Optional custom listing title. Prevents automatic metadata fetching.
description	string	Optional custom listing description. Prevents automatic metadata fetching.

curl -X POST "https://viesearch.com/api/submit" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "email": "webmaster@example.com", "category_slug": "computers_and_technology", "title": "Example", "description": "Custom description"}'

fetch("https://viesearch.com/api/submit", {
  method: "POST",
  headers: {
    "x-api-key": "vs_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com",
    email: "webmaster@example.com",
    category_slug: "computers_and_technology",
    title: "Example",
    description: "Custom description"
  })
})
.then(res => res.json())
.then(data => console.log(data));

import requests

url = "https://viesearch.com/api/submit"
headers = {
    "x-api-key": "vs_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://example.com",
    "email": "webmaster@example.com",
    "category_slug": "computers_and_technology",
    "title": "Example",
    "description": "Custom description"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

POST /api/suggest

Rate Limit: 1 request per 24 hours

Propose a new category for the Viesearch index. Suggestions are manually reviewed by our editorial team.

Parameter	Type	Description
title *	string	The name of the proposed category (3-100 chars, letters/spaces only).
parent_slug	string	The slug of the parent category (e.g., computers_and_technology).

curl -X POST "https://viesearch.com/api/suggest" \
  -H "x-api-key: vs_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Tech", "parent_slug": "computers_and_technology"}'

fetch("https://viesearch.com/api/suggest", {
  method: "POST",
  headers: {
    "x-api-key": "vs_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    title: "New Tech",
    parent_slug: "computers_and_technology"
  })
})
.then(res => res.json())
.then(data => console.log(data));

import requests

url = "https://viesearch.com/api/suggest"
headers = {
    "x-api-key": "vs_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "title": "New Tech",
    "parent_slug": "computers_and_technology"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())