Search & Discovery API
Full-text and semantic search across your debates and verdicts, with advanced filters and query suggestions.
The Search API lets you query your debate history using a combination of keyword matching, full-text search, and semantic vector search. Results are always scoped to the authenticated user's own debates.
Base URL
All endpoints below are relative to https://api.askverdict.ai. All search endpoints require authentication via Authorization: Bearer <your_api_key>.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/search | Search debates and verdicts with filters |
GET | /api/search/suggestions | Autocomplete suggestions from search history |
DELETE | /api/search/history | Clear your personal search history |
GET /api/search
/api/searchSearch your debates using keyword matching, full-text search, and semantic vector similarity. Supports advanced filters for status, mode, date range, confidence score, and verdict presence.
How Search Works
Results are produced in three stages and merged:
- Keyword (ILIKE) — Matches
questionandcontextfields with a case-insensitive substring scan. Always active. - Full-text (tsvector) — When the
search_vectorcolumn is populated by Postgres triggers,plainto_tsqueryis used to boost and rank results. - Semantic (vector) — Embeddings are generated for your query and compared against stored debate embeddings. Vector-only hits (semantically similar but not keyword-matched) are appended after keyword results.
Pagination and total counts are based on keyword results only — semantic-only additions are appended beyond the normal page boundary.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Required | Search query. 1–200 characters. Matched against debate question and context. |
type | "debates" | "verdicts" | Optional | Filter by result type. "verdicts" returns only completed debates that have a verdict. Default: "debates". |
sort | "relevance" | "date" | "popularity" | Optional | Sort order. "relevance" uses full-text rank + recency. "popularity" sorts by view count. Default: "date". |
page | integer | Optional | Page number, 1-indexed. Default: 1. |
limit | integer | Optional | Results per page. Between 1 and 50. Default: 10. |
status | string | Optional | Comma-separated status filter. Valid values: pending, running, paused, completed, failed. Example: "completed,failed". |
mode | string | Optional | Comma-separated mode filter. Valid values: fast, balanced, thorough. Example: "balanced,thorough". |
dateFrom | string (ISO 8601) | Optional | Include only debates created on or after this date. Example: "2026-01-01". |
dateTo | string (ISO 8601) | Optional | Include only debates created on or before this date (end of day inclusive). Example: "2026-02-28". |
minConfidence | number (0–100) | Optional | Include only debates with a verdict confidence at or above this percentage. Example: 70 means confidence >= 0.70. |
hasVerdict | boolean | Optional | When true, return only debates that have a verdict object. |
Example Requests
# Basic search
curl "https://api.askverdict.ai/api/search?q=microservices" \
-H "Authorization: Bearer vrd_your_api_key"
# Filter to completed debates with high confidence, sorted by relevance
curl "https://api.askverdict.ai/api/search?q=infrastructure+migration&type=verdicts&sort=relevance&status=completed&minConfidence=75&page=1&limit=20" \
-H "Authorization: Bearer vrd_your_api_key"
# Date-range filter for Q1 2026
curl "https://api.askverdict.ai/api/search?q=build+vs+buy&dateFrom=2026-01-01&dateTo=2026-03-31" \
-H "Authorization: Bearer vrd_your_api_key"Response
relevanceScore
relevanceScore is a float between 0 and 1 computed by Postgres ts_rank when full-text indexes are available. For ILIKE-only matches it is null. Semantic-only additions (appended after keyword results) also have relevanceScore: null.
Search Result Object
| Field | Type | Description |
|---|---|---|
id | string | Debate UUID |
question | string | The debate question |
status | string | Debate lifecycle status |
mode | string | null | Debate mode (fast / balanced / thorough) |
createdAt | string (ISO 8601) | When the debate was created |
completedAt | string | null | When the debate completed, or null |
recommendation | string | null | Verdict recommendation — null if no verdict yet |
oneLiner | string | null | One-line verdict summary — null if no verdict yet |
confidence | number | null | Verdict confidence between 0 and 1 |
relevanceScore | number | null | Full-text relevance score (0–1). Null for ILIKE or semantic-only matches |
Error Responses
| Status | Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | Query string validation failed — details in error.details |
401 | UNAUTHORIZED | Missing or invalid API key |
GET /api/search/suggestions
/api/search/suggestionsReturn autocomplete suggestions based on the authenticated user's previous search history and debate questions. Useful for implementing a live search-as-you-type dropdown.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Optional | Partial query string to match against. If omitted, returns recent searches. |
Example Requests
curl "https://api.askverdict.ai/api/search/suggestions?q=micro" \
-H "Authorization: Bearer vrd_your_api_key"Response
DELETE /api/search/history
/api/search/historyClear the authenticated user's entire search history. Suggestions will no longer be influenced by past queries.
Example Request
curl -X DELETE "https://api.askverdict.ai/api/search/history" \
-H "Authorization: Bearer vrd_your_api_key"Response
Advanced Filtering Tips
Combining filters
All advanced filters are combined with AND logic. For example, status=completed&minConfidence=80&mode=thorough returns only completed thorough debates with confidence ≥ 80%.
Filter Examples
| Goal | Query string |
|---|---|
| Find all failed debates | ?q=...&status=failed |
| Completed fast debates only | ?q=...&status=completed&mode=fast |
| High-confidence verdicts this month | ?q=...&type=verdicts&minConfidence=80&dateFrom=2026-02-01 |
| Debates with any verdict | ?q=...&hasVerdict=true |
| Multiple modes | ?q=...&mode=balanced,thorough |
Pagination
The API returns total (total keyword matches) and totalPages. Iterate with page=1, page=2, etc. using the same query string:
# Page 2 of results
curl "https://api.askverdict.ai/api/search?q=strategy&page=2&limit=10" \
-H "Authorization: Bearer vrd_your_api_key"Was this page helpful?