Search API

define.wtf provides two search endpoints: full-text search with FTS5 for comprehensive results, and autocomplete for real-time suggestions as users type.

Full-Text Search

GET /api/v1/search?q=TERM

Performs full-text search across acronyms and definitions in your workspace using FTS5 (Full-Text Search 5) with typo tolerance via Levenshtein distance.

Query Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	—	Search query (min 1 character)
category	string	No	—	Filter by category slug
include_deprecated	boolean	No	false	Include deprecated acronyms
limit	number	No	10	Max results (max 50)

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "acr_abc123def456",
        "type": "acronym",
        "term": "API",
        "title": "Application Programming Interface",
        "text": "A set of protocols and tools for building software...",
        "matchedIn": "term",
        "isPrimary": true,
        "netVotes": 12,
        "categories": [
          {
            "id": "cat_001",
            "name": "Technology",
            "slug": "technology",
            "color": "#FF6B6B"
          }
        ]
      },
      {
        "id": "def_xyz789",
        "type": "definition",
        "acronymId": "acr_abc123def456",
        "acronymTerm": "API",
        "title": "Application Programming Interface",
        "text": "A set of protocols and tools for building software...",
        "matchedIn": "definition",
        "isPrimary": true,
        "netVotes": 12,
        "creatorName": "Alice Chen",
        "categories": [
          {
            "id": "cat_001",
            "name": "Technology",
            "slug": "technology",
            "color": "#FF6B6B"
          }
        ]
      }
    ],
    "count": 2,
    "totalAvailable": 2
  }
}

Response Fields

Field	Type	Description
results	array	Array of matching acronyms and definitions
count	number	Number of results returned
totalAvailable	number	Total matches in database (before limit)
results[].id	string	Acronym ID (for type=acronym) or definition ID (for type=definition)
results[].type	string	Either `"acronym"` or `"definition"`
results[].term	string	The acronym term (acronyms only)
results[].title	string	Title of acronym or definition
results[].text	string	First 200 chars of description
results[].matchedIn	string	Where match occurred: `"term"`, `"title"`, or `"definition"`
results[].isPrimary	boolean	Is this the primary definition?
results[].netVotes	number	Upvotes - downvotes
results[].categories	array	Associated categories
results[].creatorName	string	Name of definition creator (definitions only)
results[].acronymTerm	string	Parent acronym term (definitions only)
results[].acronymId	string	Parent acronym ID (definitions only)

Examples

Simple search:

curl "https://engineering.define.wtf/api/v1/search?q=API" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Search with category filter:

curl "https://engineering.define.wtf/api/v1/search?q=programming&category=technology" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Search including deprecated acronyms:

curl "https://engineering.define.wtf/api/v1/search?q=OLD&include_deprecated=true" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Search with higher limit:

curl "https://engineering.define.wtf/api/v1/search?q=framework&limit=50" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Search Features

Full-text search: Searches across acronym terms, definition titles, and full text.

Typo tolerance: Uses Levenshtein distance to find similar terms (e.g., "APPI" finds "API").

Ranking: Results are ranked by:

Exact matches (highest relevance)
Prefix matches
Levenshtein distance (closest matches)
Vote score (higher votes rank higher)

Autocomplete Search

GET /api/v1/search/autocomplete?q=TERM

Real-time autocomplete suggestions as users type. Results are cached for 5 minutes.

Query Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	—	Search query (min 1 character)
limit	number	No	7	Max results (max 15)

Response

{
  "success": true,
  "data": [
    {
      "id": "acr_abc123def456",
      "term": "API",
      "title": "Application Programming Interface",
      "type": "exact_match",
      "score": 100
    },
    {
      "id": "acr_def789ghi123",
      "term": "APIM",
      "title": "API Management",
      "type": "prefix_match",
      "score": 95
    },
    {
      "id": "acr_jkl456mno789",
      "term": "APPSYNC",
      "title": "Application Synchronization",
      "type": "fuzzy_match",
      "score": 75
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Acronym ID
term	string	Acronym term
title	string	Primary definition title
type	string	Match type: `exact_match`, `prefix_match`, or `fuzzy_match`
score	number	Relevance score (0-100)

Match Types

exact_match — Full query matches term (e.g., "API" → "API")
prefix_match — Term starts with query (e.g., "AP" → "API", "APP")
fuzzy_match — Similar term using Levenshtein (e.g., "API" → "APPI", "AAPI")

Examples

Simple autocomplete:

curl "https://engineering.define.wtf/api/v1/search/autocomplete?q=AP" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Response (as user types):

{
  "success": true,
  "data": [
    {
      "id": "acr_abc123def456",
      "term": "API",
      "title": "Application Programming Interface",
      "type": "prefix_match",
      "score": 95
    },
    {
      "id": "acr_111222",
      "term": "APP",
      "title": "Application",
      "type": "prefix_match",
      "score": 90
    }
  ]
}

Autocomplete with higher limit:

curl "https://engineering.define.wtf/api/v1/search/autocomplete?q=OK&limit=15" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Caching

Autocomplete results are cached for 5 minutes per query. This improves performance for frequently searched terms. Cache is scoped per tenant and query string.

Search Best Practices

For Applications

Use autocomplete for user input fields — provide real-time suggestions as users type
Debounce autocomplete requests — wait 300ms after user stops typing before requesting
Use full-text search for browse/discover — when user explicitly searches
Cache results client-side — avoid redundant requests for the same query
Show match type — highlight exact vs. fuzzy matches for clarity

Query Tips

Search is case-insensitive — "api" = "API" = "Api"
Acronyms are uppercase — search normalizes queries to uppercase
Partial searches work — "OKR" finds "OKR", "OKRA", "OK"
Whitespace is trimmed — leading/trailing spaces are removed
Special characters are supported — "C++" searches for C++

Error Responses

Missing query (400):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid search parameters",
    "details": {
      "q": ["Search query is required"]
    }
  }
}

Query too long (400):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid search parameters",
    "details": {
      "q": ["String must contain at most 100 character(s)"]
    }
  }
}

Invalid category (400):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid search parameters",
    "details": {
      "category": ["Category not found"]
    }
  }
}

Unauthorized (401):

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required to search"
  }
}

Advanced: Search Algorithm

The search system combines multiple techniques:

FTS5 (Full-Text Search 5) — SQLite's built-in full-text search for fast, ranked results
Prefix matching — Quick term prefix search for autocomplete
Levenshtein distance — Edit distance algorithm for typo tolerance (max distance: 2)
Vote-based ranking — Results with higher votes rank higher

This hybrid approach provides both speed and relevance for both exact and fuzzy searches.

Search

On this page