---
title: "Search API"
description: "Search API reference — query syntax, filters, facets, and ranking configuration"
canonical: "https://docs.ainative.studio/docs/search/search-api"
last-updated: "2026-10-22T17:48:46.689Z"
---

# Search API

Source: https://docs.ainative.studio/docs/search/search-api

> Search API reference — query syntax, filters, facets, and ranking configuration

# Search API

Full reference for unified search, semantic search, autocomplete, trending, and recommendations.

**Base URL:** `https://api.ainative.studio`

---

## Unified Search

### Search All Content Types

<span className="badge badge--get">GET</span> `/api/v1/search`

Search across users, posts, groups, and events simultaneously. Returns up to `limit` results per category.

**Auth required.** User must belong to a tenant.

**Query parameters**

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `q` | string | Yes | — | Search query (1–200 chars) |
| `limit` | integer | No | 10 | Results per category (1–50) |
| `offset` | integer | No | 0 | Results offset |

```bash
curl "https://api.ainative.studio/api/v1/search?q=machine+learning&limit=5" \
  -H "Authorization: Bearer <your_api_key>"
```

```python
import httpx

resp = httpx.get(
    "https://api.ainative.studio/api/v1/search",
    headers={"Authorization": "Bearer <your_api_key>"},
    params={"q": "machine learning", "limit": 5},
)
results = resp.json()
```

**Response**

```json
{
  "users": [...],
  "posts": [...],
  "groups": [...],
  "events": [...]
}
```

---

### Search Users

<span className="badge badge--get">GET</span> `/api/v1/search/users`

Search for users by username, full name, or bio.

**Auth required.**

**Query parameters**

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `q` | string | Yes | — | Search query (1–200 chars) |
| `limit` | integer | No | 20 | Results limit (1–100) |
| `offset` | integer | No | 0 | Results offset |

```bash
curl "https://api.ainative.studio/api/v1/search/users?q=john&limit=10" \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "users": [
    {
      "id": "user-uuid",
      "username": "john_doe",
      "full_name": "John Doe",
      "bio": "AI researcher",
      "relevance_score": 0.94
    }
  ],
  "total": 23,
  "limit": 10,
  "offset": 0,
  "has_more": true
}
```

---

### Search Posts

<span className="badge badge--get">GET</span> `/api/v1/search/posts`

Search for posts by title or content. Only returns approved, non-deleted posts.

**Auth required.**

**Query parameters**

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `q` | string | Yes | — | Search query (1–200 chars) |
| `limit` | integer | No | 20 | Results limit (1–100) |
| `offset` | integer | No | 0 | Results offset |

```bash
curl "https://api.ainative.studio/api/v1/search/posts?q=tutorial&limit=20" \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "posts": [
    {
      "id": "post-uuid",
      "title": "Getting started with RAG",
      "content": "...",
      "author_id": "user-uuid",
      "relevance_score": 0.89
    }
  ],
  "total": 7,
  "limit": 20,
  "offset": 0,
  "has_more": false
}
```

---

### Search Groups

<span className="badge badge--get">GET</span> `/api/v1/search/groups`

Search for groups by name or description. Only returns public groups.

**Auth required.**

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `q` | string | Yes | — | Search query (1–200 chars) |
| `limit` | integer | No | 20 | Results limit (1–100) |
| `offset` | integer | No | 0 | Results offset |

```bash
curl "https://api.ainative.studio/api/v1/search/groups?q=developers" \
  -H "Authorization: Bearer <your_api_key>"
```

---

### Search Events

<span className="badge badge--get">GET</span> `/api/v1/search/events`

Search for events by title or description. Only returns public, scheduled events.

**Auth required.**

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `q` | string | Yes | — | Search query (1–200 chars) |
| `limit` | integer | No | 20 | Results limit (1–100) |
| `offset` | integer | No | 0 | Results offset |

```bash
curl "https://api.ainative.studio/api/v1/search/events?q=workshop" \
  -H "Authorization: Bearer <your_api_key>"
```

---

## Semantic Search

AI-powered vector search across conversations and documents using embeddings.

### Perform Semantic Search

<span className="badge badge--post">POST</span> `/api/v1/semantic-search`

**Auth required.** Rate limit: 100 requests per 5 minutes.

**Request body**

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | Yes | — | Search query text (1–1000 chars) |
| `limit` | integer | No | 20 | Max results (1–100) |
| `namespace` | string | No | `"default"` | Search scope / namespace |
| `search_type` | string | No | `"hybrid"` | `hybrid`, `semantic`, or `keyword` |
| `filters` | object | No | null | Metadata filters for search |
| `boost_factors` | object | No | null | Score boost factors (values 0–1) |
| `embedding_provider` | string | No | `"mock"` | `openai`, `local`, or `mock` |

```bash
curl -X POST https://api.ainative.studio/api/v1/semantic-search \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to implement rate limiting in FastAPI",
    "limit": 10,
    "search_type": "hybrid",
    "embedding_provider": "openai"
  }'
```

```python
import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/semantic-search",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={
        "query": "how to implement rate limiting in FastAPI",
        "limit": 10,
        "search_type": "hybrid",
        "embedding_provider": "openai",
    },
)
data = resp.json()
```

**Response**

```json
{
  "query": "how to implement rate limiting in FastAPI",
  "results": [
    {
      "document_id": "doc-uuid",
      "content": "Rate limiting can be implemented using...",
      "semantic_score": 0.92,
      "keyword_score": 0.74,
      "combined_score": 0.85,
      "metadata": {"source": "docs", "updated_at": "2026-04-01"},
      "source": "conversation",
      "relevance_indicators": {...}
    }
  ],
  "total_results": 1,
  "search_type": "hybrid",
  "search_time_ms": 48.2,
  "embedding_provider": "openai",
  "project_id": "project-uuid",
  "namespace": "default",
  "timestamp": "2026-04-25T10:00:00Z"
}
```

**Search types**

| Value | Behavior |
|-------|----------|
| `hybrid` | Combines vector similarity and keyword matching (recommended) |
| `semantic` | Pure vector similarity search |
| `keyword` | Traditional keyword matching |

---

### Semantic Search Health

<span className="badge badge--get">GET</span> `/api/v1/semantic-search/health`

Check semantic search service availability. No auth required.

---

### Semantic Search Capabilities

<span className="badge badge--get">GET</span> `/api/v1/semantic-search/capabilities`

Returns available embedding providers, search types, and configured limits. No auth required.

```bash
curl https://api.ainative.studio/api/v1/semantic-search/capabilities
```

**Response excerpt**

```json
{
  "embedding_providers": {
    "openai": {
      "available": true,
      "models": ["text-embedding-3-small", "text-embedding-3-large"],
      "requires_api_key": true
    },
    "mock": {
      "available": true,
      "note": "For testing purposes only"
    }
  },
  "search_types": {
    "hybrid": "Combines semantic and keyword search",
    "semantic": "Pure vector similarity search",
    "keyword": "Traditional keyword matching"
  },
  "limits": {
    "max_query_length": 1000,
    "max_results": 100,
    "rate_limit": "100 requests per 5 minutes"
  }
}
```

---

## Autocomplete Suggestions

### Get Search Suggestions

<span className="badge badge--get">GET</span> `/api/v1/public/zerodb/search/suggestions`

Get intelligent autocomplete suggestions for a partial query. Supports prefix matching, semantic similarity, and popularity ranking. Response time target: < 100 ms.

Auth is optional — pass a bearer token for personalized ranking.

**Query parameters**

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `q` | string | Yes | — | Partial query (2–500 chars minimum 2) |
| `limit` | integer | No | 5 | Max suggestions (1–20) |
| `project_id` | string | No | — | Optional UUID to scope suggestions to a project |

```bash
curl "https://api.ainative.studio/api/v1/public/zerodb/search/suggestions?q=quantum&limit=5"
```

```python
import httpx

resp = httpx.get(
    "https://api.ainative.studio/api/v1/public/zerodb/search/suggestions",
    params={"q": "quantum", "limit": 5},
)
data = resp.json()
for suggestion in data["suggestions"]:
    print(suggestion["text"], suggestion["relevance_score"])
```

**Response**

```json
{
  "suggestions": [
    {
      "text": "quantum neural networks",
      "relevance_score": 0.95,
      "category": "topic",
      "result_count": 142
    },
    {
      "text": "quantum computing",
      "relevance_score": 0.87,
      "category": "topic",
      "result_count": 156
    }
  ],
  "query": "quantum",
  "total_suggestions": 2,
  "response_time_ms": 45
}
```

**Suggestion categories**

| Category | Description |
|----------|-------------|
| `topic` | Subject or theme |
| `keyword` | Specific term |
| `entity` | Named entity (person, product, etc.) |

---

## Trending

### Trending Posts

<span className="badge badge--get">GET</span> `/api/v1/trending/posts`

Posts with highest engagement (loves, comments, shares) in a time window.

**Auth required.**

**Query parameters**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 10 | Max results (1–100) |
| `hours` | integer | 24 | Time window in hours (1–168) |

```bash
curl "https://api.ainative.studio/api/v1/trending/posts?limit=10&hours=24" \
  -H "Authorization: Bearer <your_api_key>"
```

There is also a `GET /api/v1/search/trending/posts` endpoint that accepts `time_window` as `24h`, `7d`, or `30d` instead of `hours`.

---

### Trending Groups

<span className="badge badge--get">GET</span> `/api/v1/trending/groups`

Groups with the most new member joins in a time window.

**Auth required.**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 10 | Max results (1–100) |
| `days` | integer | 7 | Time window in days (1–30) |

---

### Trending Searches

<span className="badge badge--get">GET</span> `/api/v1/trending/searches`

Most frequently searched queries.

**Auth required.**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 10 | Max results (1–100) |
| `days` | integer | 7 | Time window in days (1–30) |

---

### Trending Summary

<span className="badge badge--get">GET</span> `/api/v1/trending/summary`

Trending posts, groups, and searches in a single response. Useful for dashboard and discovery pages.

**Auth required.**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `posts_limit` | integer | 5 | Trending posts count (1–50) |
| `groups_limit` | integer | 5 | Trending groups count (1–50) |
| `searches_limit` | integer | 5 | Trending searches count (1–50) |

```bash
curl "https://api.ainative.studio/api/v1/trending/summary" \
  -H "Authorization: Bearer <your_api_key>"
```

---

### Track a Search Query

<span className="badge badge--post">POST</span> `/api/v1/trending/track-search`

Record a search query for trending analytics. Call this after a user performs a search to contribute data to the trending algorithm.

**Auth required.**

**Request body**

| Field | Type | Description |
|-------|------|-------------|
| `query_text` | string | The search query performed |
| `search_type` | string | Type of search (e.g. `"unified"`, `"semantic"`) |
| `results_count` | integer | Number of results returned |

```bash
curl -X POST https://api.ainative.studio/api/v1/trending/track-search \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "machine learning",
    "search_type": "unified",
    "results_count": 14
  }'
```

---

## Recommendations

### Recommended Posts

<span className="badge badge--get">GET</span> `/api/v1/search/recommendations/posts`

Also available at: `GET /api/v1/recommendations/posts`

Personalized post recommendations based on collaborative filtering, content similarity, and engagement signals. Excludes posts the user has already interacted with.

**Auth required.** Performance target: < 500 ms.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 10 | Max recommendations (1–50) |
| `offset` | integer | 0 | Pagination offset |

```bash
curl "https://api.ainative.studio/api/v1/recommendations/posts?limit=10" \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "recommendations": [
    {
      "post_id": "post-uuid",
      "author_id": "user-uuid",
      "author_username": "jsmith",
      "title": "Building production RAG pipelines",
      "content": "...",
      "post_type": "article",
      "tags": ["rag", "llm"],
      "loves_count": 84,
      "comments_count": 12,
      "created_at": "2026-04-20T08:00:00Z",
      "score": 0.91,
      "reasons": ["similar to posts you liked", "trending in your groups"]
    }
  ],
  "total": 1,
  "execution_time_ms": 213,
  "strategy": "hybrid"
}
```

---

### Recommended Users

<span className="badge badge--get">GET</span> `/api/v1/search/recommendations/users`

Also available at: `GET /api/v1/recommendations/users`

Users recommended for following. Based on mutual connections, similar interests, and shared groups. Excludes users already followed.

**Auth required.**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 10 | Max recommendations (1–50) |
| `offset` | integer | 0 | Pagination offset |

---

### Recommended Groups

<span className="badge badge--get">GET</span> `/api/v1/search/recommendations/groups`

Also available at: `GET /api/v1/recommendations/groups`

Groups recommended for joining. Based on user interests, groups joined by similar users, and activity level. Excludes groups the user already belongs to.

**Auth required.**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 10 | Max recommendations (1–50) |
| `offset` | integer | 0 | Pagination offset |

---

### Submit Recommendation Feedback

<span className="badge badge--post">POST</span> `/api/v1/recommendations/feedback`

Signal whether a recommendation was helpful. Used to improve future recommendation quality.

**Auth required.**

**Request body**

| Field | Type | Description |
|-------|------|-------------|
| `recommendation_type` | string | `"post"`, `"user"`, or `"group"` |
| `recommendation_id` | string | ID of the recommended item |
| `feedback` | string | `"clicked"`, `"dismissed"`, or `"reported"` |

```bash
curl -X POST https://api.ainative.studio/api/v1/recommendations/feedback \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "recommendation_type": "post",
    "recommendation_id": "post-uuid",
    "feedback": "clicked"
  }'
```

**Response**

```json
{
  "success": true,
  "recommendation_type": "post",
  "recommendation_id": "post-uuid",
  "feedback": "clicked",
  "timestamp": "2026-04-25T10:05:00Z"
}
```