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

GET /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

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

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

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

---

Search Users

GET /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

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

Response

{
  "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

GET /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

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

Response

{
  "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

GET /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

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

---

Search Events

GET /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

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

POST /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

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"
  }'

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

{
  "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

GET /api/v1/semantic-search/health

Check semantic search service availability. No auth required.

---

Semantic Search Capabilities

GET /api/v1/semantic-search/capabilities

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

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

Response excerpt

{
  "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

GET /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

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

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

{
  "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

GET /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)

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

GET /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

GET /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

GET /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)

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

---

Track a Search Query

POST /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

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

GET /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

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

Response

{
  "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

GET /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

GET /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

POST /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"

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

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