# Viesearch - Community Powered Search v7.088

> Discover websites, businesses, and resources through a curated search engine built by real people. Find what you need with quality listings powered by the community.

## Hosts

- API & Docs: [https://viesearch.com/api](https://viesearch.com/api)
- Web: [https://viesearch.com](https://viesearch.com)

## Integrate

Viesearch provides a comprehensive RESTful public API for searching the index, browsing categories, discovering trending and popular content, fetching site statistics, tracking community activity, submitting new websites, and programmatically managing support tickets.

All API requests require an API key passed in the headers:
```
x-api-key: vs_YOUR_API_KEY_HERE
```
(Human users can generate an API key in their Account Settings on the web app).

## Endpoints

All paths are relative to `https://viesearch.com`.

### Search
`GET /api/search?q={query}`
The primary search endpoint for the Viesearch index. Supports full-text search, category filtering (`c`), and multiple sorting strategies (`s`). Returns up to 25 results per page (`p`).
Sort strategies: 
- `r`: most reciprocal
- `v`: popular
- `l`: liked
- `c`: commented
- `f`: featured

### Suggestions
`GET /api/suggestions?q={query}`
Returns search suggestions based on a query or trending keywords if no query is provided.

### Categories
`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.

### Get URL Details
`GET /api/urls/{token}`
Fetches the full details of a specific listing using its unique alphanumeric token identifier. Responses are cached for 60 seconds.

### Trending
`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 (`p`).

### Popular
`GET /api/popular`
Returns the most engaged listings across the platform. Returns up to 25 results per page. Sort (`s`): `r` (most reciprocal), `l` (most liked), `c` (most commented). Paginated (`p`).

### Featured
`GET /api/featured`
Returns the current set of featured listings. Returns up to 25 results per page (`p`).

### Recent Additions
`GET /api/newest`
Returns the latest additions to the Viesearch index. Returns up to 25 results per page. Sort (`s`): `r` (recently reciprocal), `l` (recently liked), `c` (recently commented). Paginated (`p`).

### Stats
`GET /api/stats`
Returns live database statistics, including total searches, submissions, indexed sites, and category counts.

### Activity
`GET /api/activity`
Returns a paginated list of community activity, including editor registrations and community updates. Returns up to 25 items per page (`p`).

### Submit URL
`POST /api/submit`
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. JSON body requires `url`. Optional fields: `email`, `category_slug`, `title`, `description`. Rate limit: 1 request per 30 seconds.

### Suggest Category
`POST /api/suggest`
Propose a new category for the Viesearch index. Suggestions are manually reviewed by our editorial team. JSON body requires `title` and optional `parent_slug`. Rate limit: 1 request per 24 hours.

### Contact Support
`POST /api/contact`
Programmatically submit a support ticket or contact message. JSON body requires `name`, `email`, `message`. Rate limit: 1 request per 1 hour.

---

## Errors
- **HTTP 401**: Missing or invalid API key (`x-api-key`).
- **HTTP 429**: Rate limit exceeded (wait before retrying).
- **HTTP 404**: Resource or token not found.
- **HTTP 500**: Internal server error.

## Rate Limits & Pagination
- Most paginated lists enforce standard limits (25 results per page) to maintain consistency. Advance pages using `?p=2`, etc.
- All endpoints are subject to platform rate limiters. Please be respectful of API limits.

For humans looking for full details, visit: [https://viesearch.com/api](https://viesearch.com/api)