First Search Request

Use search when you already have indexed content and want immediate ranked retrieval.

Request

Node.js and Python examples use the Bulkgrid SDKs. Set BULKGRID_API_KEY in your backend environment; cURL examples also use BULKGRID_BASE_URL=https://bulkgrid.com.

import { BulkgridClient } from '@bulkgrid/sdk';

const client = new BulkgridClient({
  apiKey: process.env.BULKGRID_API_KEY ?? '',
  baseUrl: process.env.BULKGRID_BASE_URL ?? 'https://bulkgrid.com',
});

const data = await client.search({
  query: 'pricing page',
  limit: 3,
});

import os
from bulkgrid import BulkgridClient

with BulkgridClient(
    api_key=os.environ["BULKGRID_API_KEY"],
    base_url=os.environ.get("BULKGRID_BASE_URL", "https://bulkgrid.com"),
) as client:
    data = client.search({"query": "pricing page", "limit": 3})
    print(data)

curl "$BULKGRID_BASE_URL/api/v1/search" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BULKGRID_API_KEY" \
  -d '{
    "query": "pricing page",
    "limit": 3
  }'

Important request fields

query: the search text
limit: number of results to return, up to 50
collectionId: optional collection scope
fullTextWeight, semanticWeight, rrfK: ranking controls

Example response

{
  "query": "pricing page",
  "scoring": {
    "fullTextWeight": 0.3,
    "semanticWeight": 0.7,
    "rrfK": 60
  },
  "results": [
    {
      "chunk_id": "3f7a3578-7cec-4722-bab4-b37ba0b9c2ab",
      "source_document_id": "0866c8e8-a384-4f52-b83f-327a1afecf1d",
      "source_id": "a3c05cb9-5f19-4106-b8b6-b255c36c0f6d",
      "url": "https://docs.example.com/pricing",
      "title": "Pricing",
      "chunk_index": 0,
      "text_content": "Choose the plan that matches your usage...",
      "metadata": {},
      "fts_rank": 0.81,
      "semantic_rank": 0.94,
      "score": 0.9
    }
  ],
  "count": 1
}

What this tells you

search is synchronous
each result points to a source URL and source document identifiers
ranking combines lexical and semantic signals
you can use the response directly in retrieval and answer-generation workflows

Next step

Read the fuller Search.

Get started

Index

More

Access and operations

First Search Request

Request

Important request fields

Example response

What this tells you

Next step

​Request

​Important request fields

​Example response

​What this tells you

​Next step

Request

Important request fields

Example response

What this tells you

Next step