Network search

POST /api/v1/search/network

Search your team's combined network with a natural-language query, structured criteria, or both. This endpoint accepts the same filters as MCP search_network and uses the same search engine.

Provide a non-empty query or at least one of titles, industries, locations, companyLocations, or companySizes. Structured-only requests skip natural-language query parsing.

Request body

Field	Type	Description
`query`	string	Natural-language criteria, up to 1,000 characters. Optional with structured criteria.
`titles`	string[]	Job titles. Up to 50 values.
`industries`	string[]	Current-company industries. Up to 50 values.
`locations`	string[]	Where people are based. Up to 50 values.
`companyLocations`	string[]	Company headquarters locations. Up to 50 values.
`companySizes`	string[]	Up to 10 employee bands, e.g. `["201-500", "501-1000", "10001+"]`.
`similarTitles`	boolean	Include similar titles. Defaults to on at strictness 1.
`similarIndustries`	boolean	Include related industries. Default: true.
`networks`	`("user" \| "advocate" \| "organization")[]`	Networks to include. Default: all three.
`strictness`	number	Integer: 1=relaxed (default), 2=normal, 3=strict.
`asUserId`	string	Organization member whose perspective to use. Defaults to the authenticated MCP user when available, otherwise the oldest admin.
`limit`	number	Integer from 1 to 50. Default: 20.
`offset`	number	Non-negative integer. Pass the previous response's `meta.nextOffset` for the next page.
`directContacts`	`"include" \| "exclude" \| "only"`	Include people the searching user knows directly (default), exclude them, or return only them.
`excludePersonIds`	string[]	Up to 500 people to omit, such as previously shown results.
`excludeCompanies`	string[]	Current-company names to omit. Up to 50 values.
`excludeIndustries`	string[]	Current-company industries to omit. Up to 50 values.
`excludePositions`	string[]	Title keywords to omit. Up to 50 values.
`excludeConnectorPersonIds`	string[]	People no introduction route may pass through. Up to 50 values.
`excludeConnectorNames`	string[]	Connector name substrings to omit from routes. Up to 50 values.
`excludeConnectorCompanies`	string[]	Connector company names to omit from routes. Up to 50 values.
`mode`	`"auto" \| "vector" \| "neo4j" \| "prisma"`	REST-only backend selector. Default: `"auto"`. Leave unset unless you need to pin an engine.

Example

curl -X POST -H "Authorization: Bearer $KEY" \-H "Content-Type: application/json" \-d '{"query":"product managers in fintech in NYC","strictness":2}' \https://app.usehomie.com/api/v1/search/network

const res = await fetch("https://app.usehomie.com/api/v1/search/network", {method: "POST",headers: {  Authorization: `Bearer ${KEY}`,  "Content-Type": "application/json",},body: JSON.stringify({  query: "product managers in fintech in NYC",  strictness: 2,}),});const { data, meta } = await res.json();

Response

{
  "data": [
    {
      "person": { "id": "...", "name": "...", "position": "..." },
      "currentCompany": { "id": "...", "name": "..." },
      "warmness": 62,
      "connectionSources": [{ "type": "organization", "name": "Sarah" }]
    }
  ],
  "meta": {
    "searchTerms": ["product manager", "fintech", "New York"],
    "totalCount": 12,
    "returnedCount": 12,
    "backend": "neo4j-vector"
  }
}

Pass meta.nextOffset as offset with the same criteria to fetch the next page. When nextOffset is absent, there are no more results. Do not calculate the cursor from the number of returned results: filtering can skip candidates.

backend reports the engine that produced the result: neo4j-vector, neo4j-keyword, or prisma. When automatic mode has to switch engines, meta.fallback contains the original engine and the reason:

{
  "fallback": {
    "from": "neo4j-vector",
    "reason": "Vector search is not configured"
  }
}

Pinned modes return a validation error instead of falling back when the selected engine is unavailable.

Network search

Request body

Example

Response

On this page