Vector Search Preview

Search transcript segments using semantic/vector similarity. Returns timestamped clips with content metadata. Designed for external consumers (e.g. marketing pages) to surface relevant video moments from a search query.

Endpoints

GET /api/content/vector-search-preview

or with platform ID in the path:

GET /api/content/vector-search-preview/:platformId

Authentication

Optional. Uses optionalIsAuthenticated — works for both authenticated and unauthenticated users. When authenticated, platformId is inferred from the user's token.

Parameters

Path Parameters

Parameter	Type	Required	Description
platformId	number	No	Platform ID (alternative to query param)

Query Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	—	Search query, minimum 2 characters
platformId	number	Yes*	—	Platform to search within. *Can come from path, query, or auth token
limit	number	No	10	Max results to return (1–20, hard cap at 20)
scoreThreshold	number	No	0.3	Minimum similarity score (0–1)
contentIds	string	No	—	Comma-separated content IDs to restrict search to

Response

Success Response

Code: 200 OK

{
  "query": "identity in Christ",
  "count": 3,
  "items": [
    {
      "score": 0.94,
      "segment": {
        "text": "When we talk about identity in Christ, we're talking about who God says you are...",
        "start": 120.5,
        "end": 135.2
      },
      "content": {
        "id": 2256159,
        "title": "The Power of Fruit",
        "slug": "the-power-of-fruit",
        "video": "videos/1690917453595/index.m3u8",
        "featuredImage": "imported/198458_thumb.jpg",
        "duration": 331,
        "type": "video",
        "user": {
          "id": 42,
          "name": "Pastor John"
        }
      }
    }
  ]
}

Empty Response (no platformId)

Code: 200 OK

{
  "query": "identity in Christ",
  "count": 0,
  "items": []
}

Error Responses

Status Code	Code	Description
400	BAD_REQUEST	Missing or invalid q parameter (< 2 characters)
503	EMBEDDINGS_NOT_ENABLED	Embeddings generation not enabled on this node
503	SERVICE_UNAVAILABLE	OpenAI API key not configured
500	—	Internal server error

400 Example:

{
  "error": {
    "status": 400,
    "message": "Query parameter 'q' is required and must be at least 2 characters",
    "code": "BAD_REQUEST"
  }
}

503 — Embeddings not enabled:

{
  "error": {
    "status": 503,
    "message": "Vector search is not available on this node. Embeddings generation is not enabled. Set REACT_APP_ENABLE_EMBEDDINGS_GENERATION=true to enable.",
    "code": "EMBEDDINGS_NOT_ENABLED"
  }
}

503 — OpenAI not configured:

{
  "error": {
    "status": 503,
    "message": "Vector search is not available. OpenAI API key is not configured.",
    "code": "SERVICE_UNAVAILABLE"
  }
}

Notes

• Node requirement: The node must have REACT_APP_ENABLE_EMBEDDINGS_GENERATION=true set. Without this, transcript embeddings are never generated and the endpoint returns a 503 with code EMBEDDINGS_NOT_ENABLED.
• Platform scoping: platformId is required for results. Without it, an empty response is returned (not an error). This prevents cross-platform data leakage.
• Content filtering: Hidden, expired, and unpublished content is excluded. Videos must have a populated video field. Group content and premium content are still included.
• Over-fetching: The endpoint fetches 3x the requested limit from Qdrant to account for results removed by DB-level filtering.
• Score threshold: Controls minimum similarity. Lower values return more (potentially less relevant) results. Higher values are stricter.
• Hard cap: The limit parameter cannot exceed 20 regardless of what is passed.

Example

curl -X GET "https://api.tribesocial.io/api/content/vector-search-preview?q=identity+in+Christ&platformId=42&limit=5" \
  -H "Authorization: Bearer <token>"

Unauthenticated with platformId in path:

curl -X GET "https://api.tribesocial.io/api/content/vector-search-preview/42?q=identity+in+Christ&limit=5"