Search API

Unified search across companies, people, and investors with relevance scoring and advanced filtering.

Search

GET/api/v1/search

Perform intelligent search across all entities with relevance scoring, faceting, and highlighting.

Query Parameters

Parameter	Type	Description	Example
q	string	Search query (required)	?q=artificial intelligence
query	string	Alternative query parameter	?query=ai companies
type	string	Entity type to search	?type=companies
location	string	Filter by location	?location=san francisco
industry	string	Filter by industry	?industry=ai
tags	string	Filter by tags	?tags=ai,ml
sort	string	Sort by relevance or name	?sort=relevance
order	string	Sort order: asc, desc	?order=desc
min_score	number	Minimum relevance score	?min_score=50
include_highlights	boolean	Include search highlights	?include_highlights=true

Example Request

cURL

curl -X GET "https://mentibus.xyz/api/v1/search?q=artificial%20intelligence&location=san%20francisco&sort=relevance&include_highlights=true" \
  -H "Authorization: Bearer mk_your_api_key_here"

Example Response

200 OK

{
  "success": true,
  "data": {
    "results": [
      {
        "id": 1,
        "name": "OpenAI",
        "slug": "openai",
        "type": "company",
        "relevance_score": 95,
        "highlights": {
          "name": ["artificial intelligence"],
          "overview": ["artificial intelligence", "AI"]
        }
      },
      {
        "id": 1,
        "name": "Anthropic",
        "slug": "anthropic",
        "type": "company",
        "relevance_score": 87,
        "highlights": {
          "name": ["artificial intelligence"],
          "overview": ["AI safety"]
        }
      }
    ],
    "total": 2,
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    },
    "query": "artificial intelligence",
    "filters": {
      "location": "san francisco",
      "type": "all",
      "min_score": 0
    }
  },
  "message": "Search results for: "artificial intelligence" (2 total results)"
}

Categorized Search Results

When searching across all types (default), results are categorized by entity type.

Example Request

cURL

curl -X GET "https://mentibus.xyz/api/v1/search?q=fintech&location=london" \
  -H "Authorization: Bearer mk_your_api_key_here"

Example Response

200 OK

{
  "success": true,
  "data": {
    "companies": [
      {
        "id": 1,
        "name": "Revolut",
        "slug": "revolut",
        "type": "company",
        "relevance_score": 92
      }
    ],
    "people": [
      {
        "id": 1,
        "name": "Nikolay Storonsky",
        "slug": "nikolay-storonsky",
        "type": "person",
        "relevance_score": 85
      }
    ],
    "investors": [
      {
        "id": 1,
        "name": "Index Ventures",
        "slug": "index-ventures",
        "type": "investor",
        "relevance_score": 78
      }
    ],
    "total": 3,
    "facets": {
      "types": {
        "company": 1,
        "person": 1,
        "investor": 1
      },
      "locations": {
        "London, UK": 2,
        "San Francisco, CA": 1
      },
      "industries": {
        "Fintech": 2,
        "Venture Capital": 1
      }
    }
  }
}

Type-Specific Search

Search within a specific entity type for more targeted results.

Companies Only

?type=companies&q=ai

Search only within company data

People Only

?type=people&q=cto

Search only within people profiles

Investors Only

?type=investors&q=blockchain

Search only within VC firm data

Relevance Scoring

Search results are ranked by relevance score (0-100) based on match quality:

Exact Match (100)

Query matches entity name exactly

Prefix Match (90)

Query matches beginning of name

Partial Match (80)

Query appears anywhere in name

Slug Match (70)

Query matches entity slug

Description Match (60)

Query appears in description/overview

Other Fields (50)

Query matches other searchable fields

Advanced Search Features

Search with Highlights

Query

?q=artificial intelligence&include_highlights=true

Get highlighted terms in search results showing where matches occurred

Minimum Score Filtering

Query

?q=ai&min_score=80&sort=relevance

Filter results to only high-relevance matches

Multi-Field Search

Query

?q=fintech&location=london&industry=payments

Combine search with location and industry filters

Tag-Based Filtering

Query

?q=machine learning&tags=ai,ml,nlp

Filter by multiple tags simultaneously

Error Responses

400 Bad Request - Missing Query

{
  "success": false,
  "error": "Query parameter (q or query) is required",
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "v1"
  }
}

200 OK - No Results

{
  "success": true,
  "data": {
    "results": [],
    "total": 0,
    "suggestions": [
      "Try searching for "artificial intelligence"",
      "Try a broader search term",
      "Check your spelling",
      "Try using different keywords"
    ]
  },
  "message": "No search results found"
}