---
title: "Search the knowledge graph"
method: POST
path: "/v1/search"
tags: ["Search"]
---

# Search the knowledge graph

`POST /v1/search`

## Request

- Base URL: `https://brain.inite.ai`
- URL: `https://brain.inite.ai/v1/search`
- Auth: HTTP bearer

The headline read. Hybrid retrieval by default (vector + BM25 fused by reciprocal rank), router-boosted, listwise-reranked, then backfilled with each hit entity’s facts. Default semantics is Datomic-style "actual now" — only facts whose validity window contains the query moment; `asOf` slices world-time and `includeStale` reverts to the audit shape. `userId` widens the fence from tenant-global memory to tenant-global PLUS that user's personal rows (fail-closed: omitted means global only). Facts whose predicate requires a scope the caller lacks never enter the result. Fans out to the shared embedding / LLM budget, so it sits in the per-credential `expensive` throttle bucket — 10 requests/min, not the 120/min default. Source: src/search/search.controller.ts.

Required scope: `brain:read`.

## Request body

- SearchRequest
  - `asOf` string
  - `confidenceFloor` number
  - `disableLangFilter` boolean
  - `entityIds` string[]
  - `entityTypes` string[]
  - `includeContested` boolean
  - `includeRetracted` boolean
  - `includeStale` boolean
  - `limit` number
  - `minConfidence` number
  - `outputShape` 'full' | 'compact' | 'ids'
  - `predicates` string[]
  - `query` string, required
  - `queryLang` string
  - `requireProvenance` boolean
  - `searchMode` 'vector' | 'lexical' | 'hybrid'
  - `tokenBudget` number
  - `userId` string

## Response `201`

Scored entity hits with their facts.

- SearchResponse
  - `degraded` string[]
  - `linked` object[]
    - `connectionId` string, required
    - `connector` string, required
    - `hits` object[], required
      - `externalId` string, required
      - `modifiedAt` string
      - `originUri` string
      - `score` number
      - `snippet` string
      - `title` string, required
    - `observationRef` string, required
  - `results` SearchHit[], required
    - `canonicalName` string, required
    - `entityId` string, required
    - `entityType` string, required
    - `externalRefs` object, required
    - `facts` SearchFact[], required
      - `breakdown` ScoreBreakdown
      - `confidence` number, required
      - `date` string
      - `expectedUntil` string
      - `factId` string, required
      - `highlight` string
      - `mentionedAt` string
      - `object` string, required
      - `predicate` string, required
      - `predicateAlias` string
      - `scene` string
      - `score` number, required
      - `sourceKey` string
      - `status` string, required
      - `validFrom` string, required
      - `validUntil` string
    - `relations` object[]
      - `direction` 'out' | 'in'
      - `edgeId` string
      - `kind` string, required
      - `peer` string, required
      - `peerId` string
      - `peerType` string, required
      - `validFrom` string
      - `validUntil` string
    - `score` number, required

## Other responses

- `400`: Validation failed.
- `401`: Missing or unknown bearer key.
- `403`: The key lacks the required scope.
- `429`: Per-credential throttle exceeded.

---

[API](https://skmtc.dev/inite/apis/inite-brain-platform-api.md) · [All operations](https://skmtc.dev/inite/apis/inite-brain-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inite/apis/inite-brain-platform-api/revisions/c7c3eb5e304b?raw)