Search API

Full-text search and autocomplete across all learning content.

Base URL: {base-url}/search Authentication: Required (JWT)

---

Endpoints

Endpoint	Purpose
GET /	Full-text search
GET /autocomplete	Autocomplete suggestions
GET /health	Health check

---

GET /

Search across sparks, concepts, trails, and domains.

Parameters

Parameter	Type	Default	Description
q	string	required	Search query
type	enum	all	Filter: spark, concept, trail, domain
difficulty	enum	-	Filter by difficulty
page	integer	1	Page number
per_page	integer	20	Items per page

Response

{
  "data": [
    {
      "type": "spark",
      "id": "uuid",
      "slug": "attention-mechanisms",
      "title": "Attention Mechanisms",
      "summary": "...",
      "score": 0.95
    }
  ],
  "meta": { ... },
  "facets": {
    "types": { "spark": 12, "concept": 5, "trail": 2 },
    "difficulties": { "beginner": 3, "intermediate": 10 }
  }
}

---

GET /autocomplete

Quick suggestions as user types.

Parameters

Parameter	Type	Default	Description
q	string	required	Partial query (min 2 chars)
limit	integer	5	Max suggestions

Response

{
  "suggestions": [
    { "text": "attention mechanisms", "type": "spark" },
    { "text": "neural networks", "type": "trail" }
  ]
}

---

When to Use

• Search bar with autocomplete dropdown
• Search results page
• "Find content" features